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Controlling Document 



Audience 



This document describes SunCore, an implementation of the ACM SIGGRAPH 
Core System by Sun Microsystems, Inc. SunCore conforms to level 3C (dynamic 
output with 3D scaling, rotation and translation) of the Core specification for out- 
put primitives, and to level 2 (complete input) for input primitives. Appendix A 
summarizes the differences between SunCore and ACM SIGGRAPH Core System. 

The following document was used in interpreting the ACM SIGGRAPH Core Sys- 
tem: 

[1] Status Report of the Graphics Standards Planning Committee. Computer 

Graphics. Volume 13, Number 3, August 1979. 

The intended reader of this document is an applications programmer who is fami- 
liar widi interactive computer graphics and the C programming language. This 
manual contains several example programs that can be used as templates for 
larger SunCore applications. 
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Introduction 



SunCore is a comprehensive package of engineering graphics software providing 
the underlying support for interactive graphics applications programs. It is based 
on the ACM Core System, a graphics standard designed for 3D interactive graph- 
ics. 

SunCore provides extensions to the ACM Core System. These include textured 
polygon fill algorithms, raster primitives, RasterOp attributes, shaded surface 
polygon rendering, and hidden surface elimination. 

SunCore supports both the high resolution monochrome bitmap displays and the 
Sun color displays. Device-dependent functions support all these displays under 
SunCore. SunCore can also be used in conjunction with the Sun Graphics Pro- 
cessor and Graphics Buffer options. 

Note that this manual is a r^erence manual for the SunCore graphics package. It 
is not a tutorial for the programmer without knowledge of graphics principles. It 
assumes that the reader is familiar with the concepts of graphics, and has some 
familiarity with the ACM Core specification. Those who are new to graphics 
should consult one of the publications listed in Section 1.7. 

1.1. Where to Start If you are an applications programmer who is familiar with the ACM Core 

specification, but are new to SunCore, it is recommended that you read Appendix 
A in order to become familiar with the areas where SunCore deviates from and 
provides extensions to the ACM Core specification. 

Note that SunCore supports the ACM Core output level 3C, that is, dynamic out- 
put is supported, including 2 and 3D translation, scaling and rotation. SunCore 
supports the ACM Core input level 2, that is, synchronous input, including the 
PICK device. SunCore supports dimension level 2, that is, 3D operations. 

1.2. Overview and The objective of a graphics application program is drawing pictures and text on 

Terminology some display device, be it an ephemeral display device such as TV monitor or 

terminal, or a hard copy device such as a plotter or printer. 

There is a need for a device-independent way of representing graphics images in 
the computer, and having a collection of software functions map the device- 
independent representations into the physical representations that the output dev- 
ice can handle. SunCore is an implementation of one of the “standard” pack- 
ages of graphics software that have appeared recently. This section introduces 
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some of the terminology of SunCore. This terminology is used throughout this 
manual. It is somewhat easier to describe the terminology from the point of view 
of the physical device working backwards to the application program, rather than 
starting at the software and working out to the device. 

There are two quite distinct points of view for looking at a system mnning a 
graphics application: 

□ The physical device (monitor, printer, and so on) on which the final pictures 
appear, and 

□ The internal world which the programmer uses to describe the pictures, and 
which (because of SunCore) is independent of the physical device. 

A view surface is a physical surface on which the final picture appears. 

There are two interdependent sets of coordinate systems in use in the graphics 
package: 

World Coordinates 

is a coordinate system which is device-independent. The applications pro- 
grammer constmcts all graphical objects in terms of world coordinates. 

Normalized Device Coordinates 

(often abbreviated as NDC) is a fixed coordinate system which is indepen- 
dent of physical output devices. World coordinates are transformed to NDC 
space for clipping and other operations. Each physical output device driver 
then transforms from NDC space to the physical device coordinates for each 
view surface. 

A viewport is a region of NDC space which the programmer selects and on which 
the pictures will appear. 

It is the job of the viewing transformations to perform the correct mapping 
between woild coordinates and NDC space. 

A window is a region defined in world coordinates within which the images that 
the application program defines appear. The selection of the coordinates for the 
window are arbitrary — die graphics package maps the window into the 
viewport. 

In 3D, the transformation from the window to the viewport is a relatively 
straightforward process. In 3D, another level of complexity is introduced with 
the notion of a view plane which is positioned arbitrarily in world coordinates. 

An output primitive^ or often just a primitive^ is a part of a picture (such as a line 
or a character string). The appearance of primitives (such as solid or dotted 
lines) is determined by primitive attributes. A primitive attribute is a general 
characteristic of an output primitive, and affects die appearance of that primitive. 
Examples of primitive attributes are color, linestyle, and linewidth. 

Each output primitive may be assigned a name, called the pick-id, which is used 
to identify that primitive when an input operation (such as pointing at the primi- 
tive with the mouse) is applied. 
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The current position is a SunCore system value that defines the current location 
for drawing. At startup time, the current position is set to the origin of the world 
coordinate system. Functions that create output primitives (move, line, and so 
on) can alter the current position. 

Output primitives are collected together in segments. A segment defines an 
image which is a part of the picture on a view surface. 

Segments are divided into two classes, namely: temporary and retained. A 
retained segment has a name, and can have segment attributes associated with it. 
A temporary segment is nameless, and furthermore, the image that a temporary 
segment defines only remains visible as long as information is only being added 
to the view surface. As soon as a new frame action (one which repaints view sur- 
face) occurs, the temporary segment’s image disappears from the view surface. 

Each retained segment has one static attribute, its image transformation type. 

The value of this attribute can be none, translatable , or transformable. 
Translatable and transformable retained segments can be translated or 
transformed in either 2 or 3D. 

Segments also have dynamic attributes. The visibility and highlighting attributes 
control the appearance of the image. The detectability attribute determines if the 
segment can be detected by the pick device. Dynamic attributes for translatable 
and transformable segments include the segment’s image transformation. 
Depending on the image transformation type, the image transformation may con- 
tain translation, rotation, and scaling components. 

A viewing operation is an operation that maps positions in world coordinates to 
positions in NDC space. The viewing operation also determines the portion of 
the world coordinate space that is visible if window clipping or depth clipping is 
enabled. 

The applications program can obtain user interaction by means of input primi- 
tives, which provide facilities for pointing at objects, entering data from the key- 
board, and causing events. 

Basics of Drawing Pictures The general sequence of actions that an application program goes through to 

create a picture on a device is this: 

1. Initialize SunCore. 

2. Initialize a view surface upon which the picture will be drawn. 

3. Select a view surface upon which the picture will be drawn. 

4. Specify the viewing operation parameters (sires of windows in world coordi- 
nates, sire of viewport, and so on). 

5. Set an image transformation type. 

6. Create a segment. The created segment becomes the currently open segment 
until it is closed. 

7. Set attributes for the segment, if required. 
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8. Draw objects in the segment using output primitives. 

9. Close the segment. 

10. Repeat steps 4 through 9 as often as required, for as many segments as 
needed to build the picture. 

11. Apply image tran^ormations (translation, scaling, and rotation) to a given 
segment, to achieve the required picture on the display device. 

12. Deselect the view surface. 

13. Terminate SunCore. 

In providing the application programmer with the capabilities needed to draw 
pictures, SunCore breaks the interface into six functional areas: 

Control 

directs the major actions of SunCore, such as startup, shutdown, selection 
and deselection of view surfaces, and so on. 

Segments 

control the creation, closing, and removal of segments. Segments are then 
used to collect sets of: 

Output Functions 

also known as output primitives, which describe the drawing of lines and 
line sequences, shaded regions, text, and markers. 

Attributes 

control the way in which output primitives actually appear in the final image 
(solid or dotted lines, for instance). 

Transformations 

control the major appearances of pictures, such as orientation (rotation), 
scaling, and translation. Transformations also control projection type and 
clipping. 

Input Functions 

handle the interaction with the user via the keyboard and the mouse. 

1.3. Getting Started With This section provides an example of a SunCore application program. The 

SunCore glass . c program draws a martini glass on the screen. This program demon- 

strates the use of: 

□ Creating a temporary segment (see Segmentation and Naming), 

□ Moving to an absolute position (see Output Primitives), 

□ Using the polyline drawing functions (see Output Primitives), 

□ Using the absolute line drawing functions (see Output Primitives), 
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In the command line above, the options: 

-f switch causes the compiler to take advantage of floating point 

hardware if it is available. Otherwise, the compiler will emu- 
late this floating point support with software. (For more infor- 
mation on floating point options, see Appendix F). 

— Icore selects the SunCore run-time library from 

/usr/lib/libcore .a. 



— Isunwindow selects the window system library, 
— Ipixrect selects the pixrect library, 

-Im selects the correct math library. 
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When the compilation is complete, the final program is in the file glass and 
may be run by typing its name. 

This example uses the some but not all of SunC ore's capabilities. Appendix I 
contains an example that illustrates other areas of the SunCore graphics package. 

1.4. The SunCore Lint SunCore provides a lint ( 1 ) library which provides type checking beyond the 

Library capabilities of the C compiler. For example, you could use the SunCore 

lint ( 1 ) library to check a program called glas s . c with command like this: 







% lint glass. c -Icore 




V 


J 



Note that the error messages that lint ( 1 ) generates are mostly warnings, and 
may not necessarily have any effect on the operation of the program. For a 
detailed explanation of lint ( 1 ) , see the lint ( 1 ) chapter in the Program- 
ming Tools manual. 

1.5. The Coordinate Applications programs which draw pictures using SunCore communicate in 

Systems world coordinates. World coordinates are a device-independent, 2 or 3D, Carte- 

sian coordinate system for describing objects. Output primitives are given to 
SunCore functions in World Coordinates (WC). However, if world coordi- 
nate matrix is used, SunCore concatenates this matrix with the view transform so 
that output primitives are first transformed by this matrix from ‘model’ or 
‘object’ coordinates to world coordinates. This means that the user can supply 
primitives in ‘model’ coordinates, each model or object being moved into world 
coordinates according to the current world coordinate matrix. 

In 3D, the user may choose to use right-handed or left-handed world coordinates. 
In a right-handed system, if (for example) the x coordinate increases to the right 
and the y coordinate increases upwards, then the z coordinate increases towards 
the viewer. In the corresponding left-handed system, the x coordinate increases 
to the right, the y coordinate increases upwards, and the z coordinate increases 
away from the viewer. 

The composite viewing transform is formed from the world coordinate matrix 
and the viewing parameters. SunCore functions transform the output primitives 
from world (or model) coordinates to NDC, which is a left-hand coordinate sys- 
tem bounded such that: 0.0^ ,y,z <1.0 

Since current Sun view surfaces have four-to-three aspect ratios, the default NDC 
space has the y extent bounded to 0.0<y <0.75. Primitives are stored in the 
Display List (also called the Pseudo Display File or PDF), in NDC space. The 
user-specified window in world coordinates is mapped (and optionally clipped) 
to the user-specified viewport within NDC space. The entire NDC space is then 
mapped to the selected physical view surfaces. 
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1.6. Details of Using 
SunCore 



This section describes the details of creating applications programs to mn with 
SunCore. 



Classification of Functional The ACM Core specification defines levels of functional capability for a graphics 

Capabilities package which implements the specification. The table below shows the 

classification. Terms such as BUFFERED and DYNAMICA are defined as con- 
stants in the file <usercore . h>, discussed below. 



Table 1-1 Output Capabilities 



Functional Capability 


BASIC 


BUFFERED 


DYNAMICA 


DYNAMICB 


DYNAMICC 


Output Primitives and 
Primitive Attributes. 


yes 


yes 


yes 


yes 


yes 


Viewing 


yes 


yes 


yes 


yes 


yes 


Control 


yes 


yes 


yes 


yes 


yes 


Temporary Segments 


yes 


yes 


yes 


yes 


yes 


Retained Segments 


no 


yes 


yes 


yes 


yes 


Highlighting Segment 
Attribute 


no 


yes 


yes 


yes 


yes 


Visibility Segment 
Attribute 


no 


yes 


yes 


yes 


yes 


Image Transformation 
Segment Attribute 


no 


no 


yes 


yes 


yes 


Detectability Segment 
Attribute 


no 


* 

yes 


* 

yes 


* 

yes 


* 

yes 



* This feature is only available if input levels SYNCHRONOUS or COMPLETE 
are supported. Note that SunCore supports all output levels up to DYNAMICC. 



Table 1-2 Input Capabilities 



Functional Capability 


NOINPUT 


SYNCHRONOUS 


COMPLETE 


Device Initialization and Termination 


no 


yes 


yes 


Synchronous Interaction Functions 


no 


yes 


yes 


Echo Control 


no 


yes 


yes 


Explicit Enable or Disable 


no 


no 


yes 


Event Queue Management 


no 


no 


yes 


Sampled Device Functions 


no 


no 


yes 


Associations 


no 


no 


yes 



Note that SunCore supports up to the SYNCHRONOUS input level. 
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Table 1-3 Dimension Levels Supported 



Functional Capability 


TWOD 


THREED 


2D Primitives, 
Attributes, and Viewing. 


yes 


yes 


3D Primitives, 
Attributes, and Viewing. 


no 


yes 



Note that SunCore supports up to the THREED dimension level. 

Error Reporting SunCore performs consistency checks on arguments passed to its various func- 

tions. Any time an error is detected, the name of the function which raised the 
error condition and the text of the error message are printed on the standard error 
(stderr). 

All SunCore interfaces disfunctions that return a value. If a function completes 
successfully, it returns the value zero. If the function raises any error conditions, 
it returns a non-zero value. SunCore always identifies the name of the function 
which raised the error condition. The ACM Core specification defines specific 
error numbers. These do not correspond to SunCore^s error numbers in the 
current release. 

Useful Constants in the The file <user core . h> defines a collection of constants which the application 

<usercore . h> Include File programmer should use in lieu of hardwired constants in code. The constants are 

described here (but their values are not stated). 

Useful Constants'. 

TRUE A universal value denoting the tmth value. 

FALSE A universal value denoting the false value. 

MAXVSURF The maximum number of view surfaces which may be initialized 
at any one time. 

Initialization Constants. These constants describe the levels of the SunCore 
facilities which the application program will use. These constants should be used 
when calling the initial! ze_core ( ) function. 

BASIC Denotes the basic output level. See the tables above for the 
classifications. 

BUFFERED 

Denotes the buffered output level. See the tables above for the 
classifications. 



DYNAMICA 

Indicates that the application package wishes to use 2D translation 
facilities. See the tables above for the classifications. 



DYNAMICB 

Indicates that the application package wishes to use 3D scaling, rota- 
tion, and translation facilities. See the tables above for the 
classifications. 
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DYNAMICC 

Indicates that the application package wishes to use 3D scaling, rota- 
tion, and translation facilities. See the tables above for the 
classifications. 

NOINPUT Indicates that this application package will not use any input facili- 
ties. See the tables above for the classifications. 

SYNCHRONOUS 

Indicates that this application program will use synchronous input 
facilities. See the tables above for the classifications. 

COMPLETE 

SunCore does not support this input level. See the tables above for 
the classifications. 

TWOD Indicates that the application package will only use 2D functions. 

See the tables above for the classifications. 

THREED Indicates that the application package will use both 2D and 3D func- 
tions. See the tables above for the classifications. 

Character Quality Constants. These constants should be used when calling the 
set_charprecision { ) function. 

STRING Denotes low quality text. 

CHARACTER 

Denotes medium quality text 

Transform Constants. These constants should be used when calling the 
set_pro jection 0 and set_coordinate_system_type ( ) functions. 

PARALLEL 

Value to indicate parallel projection. 

PERSPECTIVE 

Value to indicate perspective projection. 

RIGHT Value to indicate right-handed world coordinate system. 

LEFT Value to indicate left-handed world coordinate system. 

Image Transformation Type Constants. These constants are used when calling 
the set_image_trans format ion_type ( ) and 
set_segment_image_transformation_type ( ) functions. 

Indicates a retained segment which cannot be transformed. 

Indicates a retained segment which may be translated in 2D. 

Indicates a retained segment which may be fiilly translated, scaled, 
and rotated, in 2D. 

Indicates a retained segment which may be translated in 3D. 

Indicates a retained segment which may be fiilly translated, scaled, 
and rotated, in 3D. 
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Line Style Constants. These constants should be used when calling the 
set_line st yle ( ) attribute for output primitives. 

SOLID Solid line. 

DOTTED Dotted line. 

DASHED Dashed line. 

DOTDASHED 

Dashed and dotted line. 

Text Font Selection Constants. These constants should be used when calling 
set_f ont ( ) . 

ROMAN For character precision, a Roman font; for string precision, a raster 
font. 

GREEK For character precision, a Greek font; for string precision, the 
default raster font. 

SCRIPT For character precision, a Script font; for string precision, a small 

raster font. 

OLDENGLISH 

For character precision, an Old English font; for string precision, 
equivalent to ROMAN. 

STICK This is equivalent to a medium sized ROMAN raster font. 

SYMBOLS This is equivalent to a bold version of STICK. It currently holds 
some electronics symbols (character values 32 through 47). 

Input Device Constants. These constants should be used when calling the 
initialize_device ( ) and terminate_device ( ) functions and other 
input functions. 

PICK The PzciJ: device. The mouse in SunCore. 

KEYBOARD 

The Keyboard device. 

STROKE The freehand STROKE device. The mouse in SunCore. 

LOCATOR The Locator device. The mouse in SunCore. 

VALUATOR 

The Valuator device. The mouse in SunCore. 

BUTTON The Button device. The mouse in SunCore. 

RasterOp Constants. These constants should be used when calling the 
set_rasterop 0 function. 

NORMAL Indicates normal copy mode. 

XORROP Indicates bitwise exclusive or of source and destination. 

ORROP Indicates bitwise or of source and destination. 
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1.7. Further Reading 



Polygon Rendering Style Constants. These constants should be used when cal- 
ling the set_polygon_interior_style () and 
set_shading_parameters ( ) functions. 

PLAIN Indicates area fill with the color indicated by the fill index primitive 
attribute. 

SHADED Indicates shading according to the current shading parameters (for 
3-D polygons only). 

CONSTANT 

Indicates constant user-specified shade. 

GOURAUD 

Indicates Gouraud shading. 

PHONG Indicates Phong shading. 

[1] Conrac Corporation. Raster Graphics Handbook, SecondPjdiiioTL Van 
Nostrand Reinhold, 1985. 

[2] J.D. Foley and A. Van Dam. Fundamentals of Interactive Computer 
Graphics. Addison-Wesley, 1982. 

[3] W.M. Newman and R.F. Sproull. Principles of Interactive Computer 
Graphics. McGraw-Hill, 1979. 

[4] ACM-SIGGRAPH. Conference Proceedings. 

[5] IEEE Computer Graphics and Applications. 

[6] Status Report of the Graphics Standards Planning Committee. Computer 
Graphics. Volume 13, Number 3, August 1979. 

[7] Special Issue on Graphics Standards. ACM Computing Surveys. Volume 
10, #4, December 1978. 

[8] The SIGGRAPH Core System Today. Computer Graphics World. Volume 
5, #8, August 1982. 

[9] SunView Programmer* s Guide. Sun Microsystems. 

[10] SunView System Programmer’s Guide. Sun Microsystems. 

[11] Pixrect Reference Manual. Sun Microsystems. 

[12] SunCGI Reference Manual. Sun Microsystems. 

[13] FORTRAN Programmer* s Guide for the Sun Workstation. Sun Microsys- 
tems. 

[14] Pascal Programmer* s Guide for the Sun Workstation. Sun Microsystems. 
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Control 

2. 1 . Initialization and Termination 

Initialize the SunCore System 

Close Down the SunCore System 

2.2. Initializing and Selecting View Surfaces 

Initialize a View Surface 

Close Down a View Surface 

Add View Surface to Selected Set 

Remove View Surface from Selected Set 

2.3. Batching of Updates 

Indicate Start of a Batch of Updates 

Indicate End of a Batch of Updates 

Start New Frame Action for Selected View Surfaces 

2.4. Error Control 

Report Most Recent Error 

Print Error 

2.5. Miscellaneous 

Drag Control (SunCore Extension) 

Signal Handling 




_2 

Control 



The SunCore graphics package provides several functions for controlling the sys- 
tem. These functions are discussed here, and the sections and subsections which 
follow describe the individual functions in detail. 

Initialization and termination 

of SunCore provide for the initialization of the package to a specific and 
predetermined state, and for closing it down when the applications program 
has finished using the graphics package. 

View surface control 

provides for the initialization, termination, and selection of view surfaces. A 
view surface must be initialized before it can be used. A view surface 
should be terminated when the applications package has finished with it. 
Functions are provided to add view surfaces to the set of selected view sur- 
faces, and to remove view surfaces from that set. View surface names in 
SunCore are structures. The vwsurf structure is declared in 
<user core . h> and is described in Appendix B. SunCore supports 
several view surfaces; see Appendix B for details of view surfaces. 

Picture change control 

provides for the “batching” of changes to dynamic segment attributes so 
that the application program may force the simultaneous occurrence of a 
group of changes. 

Frame control 

denotes the function called new_f rame ( ) , which clears the view surface 
and redraws all segments except temporary segments. 

Error handling 

is that part of SunCore concerned with reporting errors to the application 
program. 

2.1. Initialization and 
Termination 



There are two functions provided for initializing and terminating SunCore. The 
application program should call initialize_core ( ) before making any 
other calls upon the graphics system. terminate_core ( ) should be the last 
call to SunCore before the application program itself is finished. 
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Initialize the SunCore System initialize_core (output_level, input_level, dimension) 

int output_level; /* SunCore Level for Output */ 

/* BASIC, BUFFERED, DYNAMICA */ 

/* DYNAMICB, DYNAMICC */ 

int input_level; /* SunCore Level for Input */ 

/* NOINPUT, SYNCHRONOUS, COMPLETE */ 
int dimension; /* Number of Dimensions Required */ 

/* TWOD, THREED */ 

initialize_core ( ) initializes the Core graphics package to a known state. 

SunCore supports up to output level DYNAMICC of the ACM Core specification, 
up to input level SYNCHRONOUS of the ACM Core, and dimension level 
THREED of the ACM Core. 

□ The SunCore system is already initialized. 

□ The specified output level cannot be supported, 
o The specified input level cannot be supported. 

□ The specified dimension cannot be supported. 



Close Down the SunCore 
System 



terminate_core () 

terminate_core ( ) closes down the Core graphics package. 



2.2. Initializing and 
Selecting View 
Surfaces 



View surface control provides for the initialization, termination, and selection of 
view surfaces. A view surface must be initialized before it can be used. A view 
surface should be terminated when the applications package has finished with it 
Examples of view surfaces are the Sun color display and the Sun monochrome 
bitmap display. Functions provided in this category are: 

initial! ze_view_sur face 

performs the functions required to gain access to a specified view surface. 

terminate_view_surface 

terminates access to the specified view surface. 

select_view_surface 

adds the specified view surface to the set of selected view surfaces for out- 
put. 

deselect_view_surface 

removes the specified view surface from the set of selected view surfaces. 

inquire_selected_sur faces 

determines which view surfaces are currently selected (not yet imple- 
mented). 



Initialize a View Surface 



initialize_view_surf ace (surface_name, type) 

struct vwsurf *surface_name; /* See Appendix B */ 

int type; /* TRUE for hidden surface removal, 

FALSE otherwise */ 
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initialize_view_surf ace ( ) initializes the Core package for a specific 
view surface. 

The surf ace_name argument to the function specifies a physical view surface. 
View surface names in SunCore are structures. The structure is defined in 

the <usercore . h> header file. Only color or gray scale devices support 
hidden-surface removal. 

□ The view surface specified by surf ace name is already initialized. 

o The view surface specified by sur f ace_name does not have any output dev- 
ice associated with it. 

□ No other view surfaces can be initialized at this time. 

□ The specified view surface does not support hidden surface removal. 

Close Down a View Surface terminate_view_surf ace (surf ace_name) 

struct vwsurf *surface_name; /* See Appendix B */ 

terminate_view_surf ace ( ) closes down the specified view surface. 

□ The view surface specified by surf ace_naine is not initialized. 

select_view_surf ace (surface_name) 

struct vwsurf *surf ace_name; /* See Appendix B */ 

select_view_surf ace ( ) adds a specified view surface to the list of 
selected view surfaces. 

A segment is only drawn on those view surfaces marked as “selected” at the 
time that the segment is created. 

□ A segment is open. 

□ The view surface specified by surf ace_naitie is not initialized. 

□ The view surface specified by surf ace_name is already selected. 

□ The view surface specified by surf ace_name caimot be selected. 

deselect_view_surf ace (surf ace_name) 

struct vwsurf *surface_name; /* See Appendix B */ 

deselect_view_sur f ace ( ) removes a specified view surface from the list 
of selected view surfaces. 

Segments created after deselect_view_surf ace ( ) is called will not be 
drawn on the deselected view surface. 

□ A segment is open. 

o The view surface specified by surf ace_name is not selected. 



Remove View Surface from 
Selected Set 



Add View Surface to Selected 
Set 
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2.3. Batching of Updates 



Indicate Start of a Batch of 
Updates 



Indicate End of a Batch of 
Updates 



SunCore provides the facility for the application program to indicate that a 
sequence of updates is being started, and the graphics package stacks up these 
picture changes until an end_batch_of_updates ( ) function call indicates 
that the end of the sequence of updates has occurred. Picture changes or 
‘updates’ include dynamic segment attributes such as visibility, detectability, 
translate, rotate, and scale. 

begin_batch_of_updates () 

begin_batch_of_updates ( ) indicates the beginning of a batch of updates 
to the picture. All modifications to dynamic attributes of segments between calls 
to begin_batch_of_updates 0 and end_batch_of_updates ( ) are 
saved up and executed simultaneously. 

□ There has been no end_bat ch_of_updates ( ) function call since the last 
begin_batch_of_updates () function call. 

end_batch_of_updates () 

end_batch_of_updates ( ) indicates the end of a batch of updates. The 
batch of changes to dynamic attributes of segments is executed, 

□ There has been no corresponding begin_batch_of_updates ( ) function 
call. 



Start New Frame Action for 
Selected View Surfaces 



2.4. Error Control 



new_f rame () 

new_f rame { ) starts new frame action for currently selected view surfaces. 
The view surface is cleared, and all visible retained segments are redrawn. 

□ The set of currently selected view surfaces is empty. 

The following functions control the display of error information. This informa- 
tion can be used to determine the source of an error. 



Report Most Recent Error report_most_recent_error (error_nuinber) 

int *e rror_n umber ; 

report_most_recent_error ( ) obtains a copy of the most recently 
detected error number. A value of zero returned to error_number indicates 
that there has been no error since the last call on 
report_most_recent_error ( ) . 

Print Error print_error ("Your message", error_number) ; 

int error_number; 

print_error ( ) prints the message associated with this error_number on 
the standard error file (stderr). Your message is any character string that the user 
wants printed. The error message is printed on the line following “Your mes- 
sage” 
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2.5. Miscellaneous 

Drag Control (SunCore 
Extension) 



Signal Handling 



The following functions provide extensions to the Core System. 
set_drag (mode) 

int mode; /* FALSE = uses the rasterop */ 

/* set by set_rasterop */ 

/* TRUE = enable XOR' ing */ 

set_drag ( ) writes all output to the bitmap or color framebuffer with XOR- 
ing. If dragging is enabled, all output to the device drivers is done with XOR’s to 
the data in the displays. This feature makes dragging more convenient For 
example, if you want to drag segment A across segment B, leaving segment B’s 
image unaffected, do the following sequence of operations; 

n Set A visibility 

□ Set dragging 

□ Set A visibility on, 

o Drag segment A to the desired location, 
o Set A visibility ojf, 

□ Set dragging 

o Set A visibility on. 

See also: set_rasterop ( ) . 

SunCore uses the SunView Notifier to handle signals. Therefore, SunCore appli- 
cations should use the Notifier instead of explicit signal ( ) calls. See the 
manuals, SunView Programmer' s Manual and SunView System Programmer' s 
Manual. 
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Viewing Operations and Coordinate Transforms 25 

3.1. Windows, View Volumes, and Clipping 25 

3.2. Default Values of Viewing Operation Parameters 27 

3.3. Setting 3D Viewing Operation Parameters 28 

Establish Reference Point for Viewing 29 

Establish View Plane Normal Vector 30 

Establish View Plane Distance 30 

Select Projection Type 30 

Establish 2D View Up Vector 30 

Establish 3D View Up Vector 3 1 

Establish Size of 2D NDC Space 3 1 

Establish Size of 3D NDC Space 32 

Establish a Window in the View Plane 33 

Specify Planes for Depth Clipping 33 

Establish Limits of 2D Viewport 34 

Establish Limits of 3D Viewport 34 

Set Viewing Parameters 35 

3.4. Viewing Control 35 

Enable Clipping in the View Plane 35 

Enable Front Plane Depth Clipping 36 

Enable Back Plane Depth Clipping 36 

Set Output Clipping (SunCore extension) 36 

Set Coordinate System Type 36 



specify 2D World or Modelling Transform 37 

Specify 3D World or Modelling Transform 37 

Convert 2D NDC to World Coordinates 37 

Convert 3D NDC to World Coordinates 38 

Convert 2D World to NDC Coordinates 38 

Convert 3D World to NDC Coordinates 38 

3.5. Inquiring Viewing Characteristics 38 

Inquire View Reference Point 39 

Inquire View Plane Normal 39 

Inquire View Plane Distance 39 

Inquire View Depth 40 

Inquire Projection 40 

Inquire View Up 2 40 

Inquire View Up 3 40 

Inquire NDC Space 2 40 

Inquire NDC Space 3 40 

Inquire Viewport 2 40 

Inquire Viewport 3 40 

Inquire Window 40 

Inquire Viewing Parameters 41 

Inquire World Coordinate Matrix 2 42 

Inquire World Coordinate Matrix 3 42 

Inquire Inverse Composite Matrix (SunCore Extension) 42 

Inquire Viewing Control Parameters 42 




3 

Viewing Operations and Coordinate 

Transforms 

Specifying a viewing operation may be thought of as specifying the arbitrary 
orientation of a synthetic camera. The resulting view of the object (the snapshot) 
can appear on one or more view surfaces. The viewing operations are provided 
for two reasons: 

1 . To specify how much of the world coordinate space should be visible, and 

2. To specify a mathematical transformation between the world coordinate sys- 
tem and NDC space. 

A viewing operation is specified by a view volume that defines the portion of 
world coordinate space which is to be projected onto a view plane (also called a 
projection plane), and a rectangular viewport in NDC space to which the pro- 
jected image will be mapped. The viewing operation is sufficiently general as to 
support both parallel and perspective projections. The parallel projection 
includes the orthograj^c, axonometric, isometric, cavalier, and cabinet projec- 
tions, as special cases. 

Once the camera model is specified with set_view_ref erence_point ( ) , 
set_view_plane_normal ( ) , and so on, a 4 x 4 view transform matrix is 
constructed. Then the process of generating an image on a view surface is: 

1. View-transforming the output primitives (using the view transform preceded 
by any modelling transform the user has specified) to NDC space. 

2. Optional clipping to the window. 

3. Scale the output to map the window to the viewport. 

4. Optional image transformation as specified by dynamic segment attributes. 

5. Optional clipping to the viewport 

6. Convert to device coordinates and draw the picture. 

3.1. Windotvs, View The window is the bounded portion of the view plane containing projected 

Volumes, and Clipping objects which will appear within the viewport on the view surface. The view sur- 
face corresponds to the physical device on which the picture is drawn. The win- 
dow is the logical region, specified in world coordinates, in which the image 
appears. 
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Specifying a window involves defining a coordinate system for the view plane. 
The coordinate system for die view plane is called the uvw coordinate system, to 
distinguish it from the world coordinate system and the NDC space, both of 
which are xyz coordinate systems. 

The origin of the uvw coordinate system is at the point where the line through the 
view reference point parallel to the view plane normal vector intersects the view 
plane. In the default case, die view plane distance is zero, and so the view refer- 
ence point lies in the view plane and is the origin of the uvw coordinate system. 

The direction of the v-axis is determined from the view up vector. The view up 
vector is specified in worid coordinates relative to the view reference point. 

The positive u-axis of the uvw coordinate system is 90 degrees clockwise from 
the positive V axis, as viewed in the direction of the view plane normal vector. 
The positive U and V axes, together with the view plane normal vector, form a 
left handed coordinate system. The window is specified in terms of maximum 
and minimum u and v values (see the set_window ( ) function). Figure 3-1 
shows the various components of the viewing system. 



Front 

Clipping Plane 




Projection 



Figure 3-1 Components of Viewing System 
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3.2. Default Values of 
Viewing Operation 
Parameters 

Table 3-1 Default Values of Viewing Operation Parameters 



Parameter 


Default Value 


View Reference Point 


{0, 0, 0} 


View Plane Normal 


{0,0.-i} 


View Distance 


0 


Front Distance 


0 


Back Distance 


1 


Type of Projection 


Parallel (0, 0, 1) 
(perpendicular to the uv 
plane) 


Window 


(0, 1,0,0.75) 


View Up Vector 


(0,1,0) 


NDC Space 


0.0^ ,2 <1.0 
0.0<y<0.75 


Viewport 


(0.0, 1.0, 0.0, 0.75,0.0, 1.0) 



Table 3-2 Default Values of Viewing Control Parameters 



Parameter 


Default Value 


Window Clipping 


On 


Output Clipping 


Off 


Front Plane Clipping 


Off 


Back Plane Clipping 


Off 


World Coordinate System 


Right handed 



Table 3-3 World Coordinate Matrix Parameters (Modelling Transform) 
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Table 3-4 Image Transformation Parameters 



Parameter 


Default Value 


SX, SY, SZ 
AX, AY, AZ 
TX, TY, TZ 


1, 1, 1 (no scaling) 

0, 0, 0 (no rotation) 

0, 0, 0 (no translation) 



3.3. Setting 3D Viewing SunCore provides a number of functions for setting parameters of the viewing 

Operation Parameters operations. There are a number of separate calls available for setting individual 

parameters, then there is a composite set_viewing_parameter s ( ) func- 
tion which sets all the viewing parameters in one fell swoop. The individual 
calls provided are summarized here and described in detail in the subsections fol- 
lowing. 
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Table 3-5 Summary of Functions for Setting Viewing Control Parameters 



Function 


Description 


set_view_reference_point 


Sets the view reference point in world 
coordinates. 


set view_jplane_normal 


Defines a vector which determines the 
view plane, relative to the view refer- 
ence point. 


set_view_plane_distance 


Defines the view plane distance from the 
view reference point along the view 
plane normal vector. 


set_view_depth 


Defines the distance from the view 
reference point to the ‘front’ clipping 
plane (also known as the ‘hither’ or 
‘near’ clipping plane) and the distance 
from the view reference point to the 
‘back’ clipping plane (also known as the 
‘yon’ or ‘far’ clipping plane). 


set_pr eject ion 


Selects perspective or parallel projec- 
tion, and defines the center of projection 
(for PERSPECTIVE projection) or direc- 
tion of projection (for PARALLEL pro- 
jection). 


set view up 2 


Establish the view up direction in the 


set_view_up_3 


view plane for 2 or 3D viewing. 


set_window 


Establishes the window boundaries in 
the view plane. 


set viewport 2 


Establish the viewport boundaries in 


set_viewport_3 


NDC space for 2 or 3D viewing. 


set ndc space 2 


Establish the size of NDC space for 2 or 


set_ndc_space_3 


3D viewing. 


set_viewing_j>arameters 


is a composite function which does all 
of the above functions at one time. 



None of the above calls have any effect until the next call upon the 

Great e_retained_segment ( ) or create_temporary_segment ( ) 

functions. 



Establish Reference Point for set_view_reference_point (x, y, z) 

Viewing float x, y, z; /* x, y, and z coordinates */ 



set_view_ref erence_jpoint ( ) sets the view reference point in world 
coordinates, x, y, and z are the coordinates of the view reference point. In the 
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absence of a specified reference point, the default view reference point is 
(0, 0, 0). The new reference point does not take effect until a new segment is 
created. 



Establish View Plane Normal set_view_plane_nonnal (dx_norm, dy_norm, dz_norm) 

Vector float dx_norm, dy_nonn, dz_norm; 

set_view__plane_normal ( ) defines a vector relative to the view reference 
point, in world coordinates. The view plane is perpendicular to the view plane 
normal vector. In the absence of any information to the contrary, SunCore estab- 
lishes the view plane normal vector as (0, 0, -1). The new vector does not take 
effect until a new segment is created. 

□ No view plane normal direction can be established because dx norm, 
dy_normj and dz_norm are all zero. 

Establish View Plane Distance set_view_plane_distance (distance) 

float distance; 

set_view_plane_distance ( ) establishes the view, or projection, plane. 
The view plane is perpendicular to the view plane normal vector, and is distance 
from the view reference point along the view plane normal vector. Distances are 
measured in world coordinate units from the view reference point. Positive 
values of distance correspond to the direction of the view plane normal vector, 
and negative values correspond to the opposite direction. In the absence of any 
information to the contrary, distance is set to zero, which means that the viewing 
plane is located at the view reference point. 



Select Projection Type set_projection (projection, dx_proj, dy_proj, dz_proj) 

int projection; /* Projection type */ 

/* PARALLEL; PERSPECTIVE */ 
float dx_j)roj, dy_proj, dz_proj; 

/* X, y, and z Deltas of Projection Point */ 

set_pr o j ect ion ( ) selects the projection system for displaying. The argu- 
ments dx _proj, dy j>roj, and dz _proj specify a world coordinate point relative to 
the view reference point. If projection is PARALLEL, objects project onto the 
view plane along lines parallel to the vector specified by dx _proj, dy _proj , and 
dz _proj. If projection is PERSPECTIVE, (dx _proj, dy _proj, dz _proj) specify a 
point in world coordinates relative to the rrference point called the center of 
projection (often abbreviated to COP). Objects project onto the view plane along 
lines travelling towards this point. Thus the center of projection is the apex of a 
pyramid whose edges pass through the four corners of the view window. 

□ The direction of projection cannot be established because dx, dy, and dz are all 
zero. Note that this error is only applicable if parallel projection was selected. 



Establish 2D View Up Vector 



set_view_up_2 (dx, dy) 

float dx, dy; /* dx and dy coordinates */ 

set_view_up_2 ( ) establishes a view up vector in 2D. This vector defines 
the direction of ‘up* for the window in world coordinates. 
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□ The view up vector cannot be established because dx, and dy are both zero. 

Establish 3D View Up Vector set_view_up_3 (dx_up, dy_up, dz_up) 

float dx_up, dy_up, dz_up; 

/* X, y, and z Deltas of View Up Vector */ 

set_view_up_3 ( ) establishes a view up vector in 3D. The three arguments 
dx up, dy_up, and dz up establish a view up vector relative to the view reference 
point. The view up vector, when projected onto the view plane in the direction 
of the view plane normal vector, specifies the positive v-axis of the uvw coordi- 
nate system in the view plane. The w-axis is also in the view plane, such that the 
u-axis, the v-axis, and the view plane normal vector form a left handed coordi- 
nate system. The v-axis is vertical and the «-axis increases to the right when the 
view plane is mapped onto the view surface. 

SunCore establishes the default view up vector as (0, 1, 0), which means that the 
y-axis is up. 

If the view plane normal vector is parallel to the y-axis, this does not work and so 
SunCore checks the view transforms for validity when creating a segment. Sun- 
Core may generate the error message: 

'The current viewing specification is inconsistent' 

□ No view plane normal direction can be established because dx up, dy up, and 
dzjip are all zero. 

set_ndc_space_2 (width, height) 
float width, height; 

set_ndc_space_2 ( ) defines the size of the NDC space which can be 
addressed on the view surface of all display devices available to the applications 
program and within which viewports may be established. Both width and height 
must be in the range of 0.0 to 1.0, and at least one of the parameters must have a 
value of 1.0. NDC space ranges from 0.0 to width in the horizontal direction and 
from 0.0 to height in the vertical direction. The rectangle defined by this func- 
tion is mapped to the viewable area of any display device available to the appli- 
cation program so that the entire rectangle is visible. Only uniform scaling of the 
rectangle is allowed; no changes can be made to the viewport aspect ratio. Sun- 
Core maximizes the usable area of the display and centers NDC space on each 
view surface. 

The default NDC specification is width=\.Q and height=0.15. Either of the 
set_ndc_space_2 ( ) or set_ndc_space_3 ( ) (see below) functions may 
be used at most once per initialization of SunCore, and the NDC space esta- 
blished applies to all view surfaces which the application program might use. 

Ten SunCore functions require that NDC space be established before ttey com- 
plete execution. If NDC space has not been explicitiy defined before any of these 
functions are executed, they implicitly define the NDC space using default values. 
Functions which implicitly define NDC space are: 



Establish Size of 2D NDC 
Space 
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□ initialize_device ( ) 
o initialize_group ( ) 

□ create_retained_seginent ( ) 

□ create_temporary_segment 0 

□ set_viewport_2 ( ) 

□ set_viewport_3 0 

□ set_viewing_j5arameters ( ) 

□ inquire_viewport_2 ( ) 

□ inquire_viewport_3 ( ) 

□ inquire_viewing_parameters 0 

The depth of NDC space is set to 0.0 if set_ndc_space_2 ( ) is used in a 3D 
implementation. 

□ set_ndc_space_2 () or set_ndc_space_3 ( ) has already been called 
since the system was initialized. 

□ set_ndc_space_2 ( ) or set_ndc_space_3 ( ) has been called too late 
— the default values have already been defined implicitly. 

□ A parameter is outside the range 0.0 to 1.0. 

□ One of width or height must have a value of 1.0. 

□ width or height has a value of 0.0. 

Establish Size of 3D NDC 
Space 



The default NDC specification is width=\Siy height=0.15^ and depth=\.0. Either 
of the set_ndc_space_3 ( ) or set_ndc_space_2 ( ) (see above) func- 
tions may be used at most once per initialization of SunCore, and the NDC space 
established applies to all view surfaces which the application program might use. 
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set_ndc_space_3 (width, height, depth) 
float width, height, depth; 

set_ndc_space_3 { ) defines the size of the NDC space which can be 
addressed on the view surface of all display devices available to the applications 
program and within which viewports may be established. 3D NDC space is a rec- 
tangular parallelepiped lying within the NDC system. This coordinate system is 
always left-handed, with the x-axis increasing to the right, the y-axis increasing 
upwards, and the z-axis increasing away from the viewer. All of the parameters 
width, height, and depth must be in the range of 0.0 to 1.0, and at least one of 
width or height must have a value of 1.0. NDC space ranges from 0.0 to width in 
the horizontal direction, from 0.0 to height in the vertical direction, and from 0.0 
to depth in the direction away from the viewer. The rectangle of size width by 
height in the z=0 plane of NDC space is mapped to the viewable area of any 
display device available to the application program so that the entire rectangle is 
visible. Only uniform scaling of the rectangle is allowed — no changes can be 
made to the viewport aspect ratio. SunCore maximizes the usable area of the 
display and centers NDC space on each view surface. 
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Ten SunCore functions require that NDC space be established before they com- 
plete execution. If NDC space has not been explicitly defined before any of these 
functions are executed, they implicitly define the NDC space using default values. 
Functions which implicitly define NDC space are: 

□ initialize_device ( ) 

□ initialize_group 0 

□ create_retained_segment ( ) 

□ create_temporary_segment ( ) 
o set_viewport_2 0 

□ set_viewport_3 ( ) 

□ set_viewing_parameters ( ) 

□ inquire_viewport_2 ( ) 

□ inquire_viewport_3 ( ) 

□ inquire_viewing_parameters ( ) . 

□ set_ndc_space_2 ( ) or set_ndc_space_3 ( ) has already been called 
since the system was initialized. 

□ set_ndc_space_2 ( ) or set_ndc_space_3 ( ) has been called too late 
— the default values have already been defined implicitly. 

o A parameter is outside the range 0.0 to 1.0. 

o One of width or height must have a value of 1 .0, 

□ width or height has a value of 0.0. 

Establish a Window in the set_window(umin, umax, vmin, vmax) 

View Plane float umin, umax; /* Left and Right sides of window */ 

float vmin, vmax; /* Bottom and Top of window */ 

set_window ( ) establishes a window, defined by four coordinates in the uv 

coordinate system, in the view plane. SunCore establishes the default window as 
(0.0, 1.0, 0.0,0.75). 

o umin is greater than or equal to umax, which means that the left side of the 
window is congruent with or to the right of the right side of the window. 

□ vmin is greater than or equal to vmax, which means that the top of the window 
is congruent widi or below the bottom of the window. 

Specify Planes for Depth set_view_depth (f ront_distance, back_distance) 

Clipping float f ront_distance, back_distance; 

/* Distances to Front and Back Planes */ 

set_view_depth ( ) defines the front and back planes for depth clipping. 
Clipping to these depth bounds is controlled by 
set_f ront_plane_clipping ( ) and 

set_back_plane_clipping ( ) . The front and back planes determine the 
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Establish Limits of 2D 
Viewport 



Establish Limits of 3D 
Viewport 



3D view volume which is mapped to the 3D viewport. 

SunCore initializes the front distance to 0.0 and the back distance to 1.0. 

□ front _distance is greater than backjcUstance^ so that the back clipping plane is 
in front of the front clipping plane. 

set_viewport_2 (xmin, xmax, ymin, ymax) 

float xmin, xmax; /* Left and Right sides of Viewport */ 
float ymin, ymax; /* Bottom and Top of Viewport */ 

set_viewport_2 ( ) establishes the limits of the viewport in 2D NDC space. 
The limits must lie in the range: 0^‘^DCmdth and 0<y <SMNDCheight SunCore 
establishes the viewport to (0.0, 1.0, 0.0, 0.75) at initialization time. 

□ xmin is greater than or equal to xmax, which means that the left side of the 
viewport is congment with or to the right of the right side of the viewport. 

□ ymin is greater than or equal to ymax, which means that the top of the viewport 
is congment with or below the bottom of the viewport. 

□ Viewport exceeds NDC space. 

set_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float xmin, xmax; /* Left and Right sides of Viewport */ 

float ymin, ymax; /* Bottom and Top of Viewport */ 

float zmin, zmax; /* Front and Back of Viewport */ 

set_viewport_3 ( ) establishes the limits of the viewport in 3D NDC space. 

The limits must lie in the range: 0^^DCwidth,0<y<.SMNDCheight, and 
0^<NDCdepth SunCore establishes the viewport to (0.0, 1.0, 0.0, 0.75, 0.0, 1.0) 
at initialization time. 

□ xmin is greater than or equal to xmax, which means that the left side of the 
viewport is congment with or to the right of the right side of the viewport. 

o ymin is greater than or equal to ymax, which means that the top of the viewport 
is congment with or below the bottom of the viewport. 

□ zmin is greater than or equal to zmax, which means that the front of the 
viewport is congment with or behind the back of the viewport. 

□ Viewport exceeds NDC space. 
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Set Viewing Parameters set_viewing_j>arameters ( view_j>arameters ) 

struct { 

float vwrefpt[3]; /* x, y, z */ 
float vwplnorm[3]; /* dx, dy, dz */ 

float viewdis; /* View Reference Point to View Plane */ 
float frontdis; /* View Reference Point to Front Clip Plane 
float backdis; /* View Reference Point to Back Clip Plane * 
int projtype; /* PARALLEL or PERSPECTIVE */ 
float projdir[3]; /* Meaning depends on projection type */ 
float window[4]; /* umin, umax, vmin, vmax */ 
float vwupdir[3]; /* dx, dy, dz */ 

float viewport [6]; /* xmin, xmax, ymin, yinax, zmin, zmax */ 
} *view_parameters; 

set_viewing_j>arameters ( ) specifies all the viewing parameters with a 
single function call. The view _parameters argument is a pointer to a structure as 
defined above. set_viewing_j)arameter s ( ) fills in the associated struc- 
ture with the current values of the viewing parameters. The parameters are: 

vwrefpt An array of three f loats describing the coordinates of the view 
reference point. 

vwplnorm An array of three floats describing the direction of the view plane 
normal vector. 

viewdis A float describing the distance of the view plane from the view refer- 
ence point. 

frontdis A float describing the front clipping distance. 
backdis A float describing the back clipping distance. 
projtype A int describing the projection type. 

projdir An array of three f loats describing the direction of projection. 

The meaning of projdir is dependent on the projection type: 

PARALLEL projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

window An array of four floats describing the boundaries of the viewing 
window. 

vwupdir An array of three floats describing the view up direction. 
viewport An array of six f loats describing the boundaries of the viewport. 

3.4. Viewing Control The functions described in the following sections allow the user to control view- 

ing attributes like clipping and coordinate systems. 

Enable Clipping in the View set_window_clipping (on_of f ) 

Plane on_off; /* TRUE = turn clipping on */ 

/* FALSE = turn clipping off */ 
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set_window_clipping ( ) enables or disables clipping against the window 
in the view plane. The argument specifies whether window clipping is 

enabled or not. A value of FALSE disables window clipping, whereas a value of 
TRUE enables window clipping. 

When window clipping is offy objects described to SunCore are not checked to 
insure that they lie within the window when projected onto the view plane. 

When window clipping is on, objects described to SunCore are clipped to the 
window. 

SunCore initializes window clipping to TRUE. 

Note that window clipping is done before segment primitives are written to the 
pseudo display file. This means that subsequent image transformations may 
extend images beyond the bounds of the viewport SunCore has optional output 
clipping (an extension to the ACM Core specification) to correct for this. See the 
set_output_clipping ( ) function described below. 

Enable Front Plane Depth set_f ront__plane_clipping ( f ront_on_of f ) 

Clipping int front_on_off ; 

set_f ront_plane_clipping ( ) enables or disables clipping against the 
front clipping plane. The front on ojf specifies clipping enabled or 

disabled for the front clipping plane. A value of FALSE means disable the clip- 
ping, and a value of TRUE enables the clipping. Clipping is disabled by default. 

s e t_ba c k_j> 1 ane_c 1 ipping ( ba c k_on_o f f ) 
int back_on_off; 

set_back_plane_clipping ( ) enables or disables clipping against the 
back clipping plane. The back on off axgament specifies clipping enabled or 
disabled for the back clipping plane. A value of FALSE means disable the clip- 
ping, and a value of TRUE enables the clipping. Clipping is disabled by default. 

Set Output Clipping (SunCore set output clipping (on of f ) 

extension) on_off; /* true = turn on clipping */ 

/* FALSE = turn off clipping */ 

SunCore supports output clipping, which is done after image transformations on 
segments, as an option in addition to window clipping. The 
set_output_clipping ( ) function enables or disables output clipping. If 
output clipping is enabled, it places a clipping process after the image transfor- 
mation specified by the dynamic segment attribute. This ensures that everything 
is correctly clipped to the viewport. 

Set Coordinate System Type set_coordinate_system_type (type) 

int type; /* RIGHT = right handed coordinates */ 

/* LEFT = left handed coordinates */ 

set_coordinate_system_type ( ) selects a left-handed or right-handed 
world coordinate system. 



Enable Back Plane Depth 
Clipping 
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Specify 2D World or 
Modelling Transform 



Specify 3D World or 
Modelling Transform 



set_world._coordinate_matrix_2 (array) 
float array [ 3 ] [ 3 ]; /* [row] [column] */ 

set_world_coordinate_matrix_2 ( ) specifies a 3 x 3 matrix containing 
the ‘world transform’ or modelling transform. This matrix is concatenated with 
the ‘viewing transform’ to give the ‘composite viewing transform’. The compo- 
site viewing transform is the transform that is actually used for all SunCore view- 
ing transform operations. The default world coordinate matrix is the identity 
matrix. Currentiy, this function does not modify column 2 of the matrix. This 
function may be called at any time, even in the midst of putting output primitives 
into a segment. 

Note that the matrix order is such that: 



xnew =x* array ofi+y* array j Q+array 2 0 



ynew =x* array Qi+y* array i,i+u/Toy 2,1 



set_world_coordinate_matrix_ 3 (array) 
float array [ 4 ] [ 4 ]; /* [row] [column] */ 

set_world_coordinate_matrix_3 ( ) specifies a 4 x 4 matrix containing 
the ‘world transform’ or modelling transform. This matrix is concatenated with 
the ‘viewing transform’ to give the ‘composite viewing transform’. The compo- 
site viewing transform is the transform that is actually used for all SunCore view- 
ing transform operations. The default world coordinate matrix is the identity 
matrix. Currently, this function does not modify column 3 of the matrix. This 
function may be called at any time, even in the midst of putting output primitives 
into a segment. 

Note that the matrix order is such that: 
xnew =x* array QQ+y* array j q+z * array ^fi^array 30 



ynew =x* array Qi+y*array 1 i+z*array 2^1+a/ray 3 j 



znew =x*array Q^+y* array i ^+z* array 2;i+array 32 



Convert 2D NDC to World map_ndc_to_world_2 (ndcx, ndcy, wldx, wldy) 

Coordinates float ndcx, ndcy; 

float *wldx, *wldy; 

map_ndc_to_world_2 ( ) maps a point in NDC space to its world coordi- 
nates. 
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Convert 3D NDC to World map_ndc_to_world_3 (ndcx, ndcy, ndcz, wldx, wldy, wldz) 

Coordinates float ndcx, ndcy, ndcz; 

float *wldx, *wldy, *wldz; 

map_ndc_to_wor ld_3 ( ) maps a point in NDC space to its world coordi- 
nates. 



Convert 2D World to NDC 
Coordinates 



Convert 3D World to NDC 
Coordinates 



3.5. Inquiring Viewing 
Characteristics 



map_world_to_ndc_2 (wldx, wldy, ndcx, ndcy) 
float wldx, wldy; 
float *ndcx, *ndcy; 

map_world_to_ndc_2 ( ) maps a point in world coordinates to its NDC 
space. 

map_world_to_ndc_3 (wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz; 
float *ndcx, *ndcy, *ndcz; 

map_world_to_ndc_3 ( ) maps a point in world coordinates to its NDC 
space. 

SunCore provides a number of functions for inquiring about parameters of the 
viewing operations. There are a number of separate calls available for inquiring 
about individual parameters, then there is a composite 

inquire_viewing_j>arameter s ( ) function which obtains all the viewing 
parameters in one fell swoop. The individual calls provided are summarized here 
and described in detail in the subsections following. 
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Table 3-6 Summary of Functions for Inquiring Viewing Parameters 



Function 


Description 


inquire_view_ref erence_point 


Obtains the view reference point in world coordinates. 


inquire view plane_normal 


Obtains a vector which determines the view plane, relative to 
the view reference point 


inquire_view_plane_di stance 


Obtains the distance from the view reference point to the 
view plane. 


inquire view depth 


Obtains the distance from the view reference point to the 
‘front’ clipping plane (also known as the ‘hither’ or ‘near’ 
clipping plane), and the distance from the view reference 
point to the ‘back’ clipping plane (also known as the ‘yon’ or 
‘far’ clipping plane). 


inquire_pro jection 


Determines which projection type is in use, and returns 
either the center of projection (for PERSPECTIVE projection) 
or direction of projection (for PARALLEL projection). 


inquire view up 2 


Determines the view up direction in 2D. 


i nqu i r e_v i e w_up_3 


Determines the view up direction in 3D. 


inquire_viewport 2 


Obtains the coordinates of the 2D viewport. 


inquire_viewport 3 


Obtains the coordinates of the 3D viewport. 


inquire window 


Obtain the boundaries of the viewing window. 


inquire_viewing parameters 


is a composite function which does all of the above functions 
at one time. 


inquire ndc space 2 


Determine the size of the NDC space in 2D. 


inquire_ndc space 3 


Determine the size of the NDC space in 3D. 



Inquire View Reference Point inquire_view_reference_point (x, y, z) 

float *x, *y, *z; /* x, y, and z Coordinates */ 

inquire_view_ref erence_point ( ) obtains the coordinates of the view 
reference point 



Inquire View Plane Normal inquire_view_plane_nonnal (dx, dy, dz) 

float *dx, *dy, *dz; /* x, y, and z deltas */ 

inquire_view_plane_normal ( ) obtains the coordinates of the view 
plane normal vector. 



Inquire View Plane Distance 



inquire_view__plane_distance (view_distance) 
float *view distance; 



inquire_view_plane_di stance ( ) obtains the distance of the view 
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Inquire View Depth 



Inquire Projection 



Inquire View Up 2 



Inquire View Up 3 



Inquire NDC Space 2 



Inquire NDC Space 3 



Inquire Viewport 2 



Inquire Viewport 3 



Inquire Window 



plane from the view reference point. 

inquire_view_depth (f ront_distance, baclc_distance) 
float *f ront_distance/ *back_distance; 

inquire_view_depth ( ) obtains the distances of the front and back clipping 
planes from the view reference point. 

inquire_pro jection (pro jection_type, dx, dy, dz) 
int *pro jection_type; 

float *dx, *dy, *dz; /* x, y, and z deltas */ 

inquire_pro jection ( ) obtains the current projection type and the coordi- 
nates of the center of projection (for PERSPECTIVE projections) or the direction 
of projection (for PARALLEL projections). 

inciuire_view_up_2 (dx, dy) 

float *dx, *dy; /* x and y directions */ 

inquire_view_up_2 ( ) obtains the view up direction in 2D. 
inquire_view_up_3 (dx, dy, dz) 

float *dx, *dy, *dz; /* x, y, and z directions */ 

inquire_view_up_3 ( ) obtains the view up direction in 3D. 

inquire_ndc_space_2 (width, height) 
float *width, *height; 

inquire_ndc_space_2 ( ) obtains the dimensions of the 2D NDC space. 

inquire_ndc_space_3 (width, height, depth) 
float *width, *height, *depth; 

inquire_ndc_space_3 ( ) obtains the dimensions of the 3D NDC space. 

inquire_viewport_2 (xmin, xmax, ymin, yinax) 
float *xmin, *xmax; 
float *ymin, *ymax; 

inquire_viewport_2 ( ) obtains the coordinates of the 2D viewport. 

inquire_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float *xmin, *xmax; 
float *ymin, *ymax; 
float *zmin, *zmax; 

inquire_viewport_3 ( ) obtains the coordinates of the 3D viewport. 

inquire_window (umin, umax, vmin, vmax) 
float *umin, *umax; 
float *vmin, *vmax; 

inquir e_window ( ) obtains the boundaries of the viewing window. 
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Inquire Viewing Parameters inquire_viewing_parameters (view_parameters) 

struct { 

float vwrefpt[3]; /* x, y, z */ 
float vwplnorm[3]; /* dx, dy, dz */ 

float viewdis; /* View Reference Point to View Plane */ 
float frontdis; /* View Reference Point 
to Front Clip Plane */ 
float backdis; /* View Reference Point 
to Back Clip Plane */ 

int projtype; /* PARALLEL or PERSPECTIVE */ 
float projdir[3]; /* Meaning depends 
on projection type */ 

float window[4]; /* umin, umax, vmin, vmax */ 
float vwupdir[3]; /* dx, dy, dz */ 
float viewport [6]; /* xmin, xmax, ymin, 
ymax, zmin, zmax */ 

} *view_parameters; 

inquire_viewing_parameter s ( ) returns a collection of information per- 
taining to the current parameters of the viewing system. The view _parameters 
argument is a pointer to a stmcture as defined above. 

inquire_viewing_parameter s ( ) fills in the associated stmcture with 
the current values of the viewing parameters. The parameters are: 

vwr^t An array of three floats describing the coordinates of the view 

reference point. 

vwplnorm An array of three floats describing the direction of the view plane 
normal vector. 

A float describing the distance of the view plane from the view 
reference point. 

A float describing the front clipping distance. 

A f J.oat describing the back clipping distance. 

A int describing the projection type. 

An array of three floats describing the direction of projection. 

The meaning of projdir is dependent on the projection type: 

PARALLEL 

projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

An array of four floats describing the boundaries of the viewing 
window. 

An array of three floats describing the view up direction. 

An array of six floats describing the boundaries of the viewport. 
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Inquire World Coordinate 
Matrix 2 


inquire world coordinate matrix 2 (array) 
float array [3] [3]; /* array [row] [col] */ 




inquire_world_coordinate_matrix_2 ( ) returns a 3 by 3 matrix con- 
taining die ‘world transform’ or modelling transform. This matrix is con- 
catenated with the ‘viewing transform’ to give the ‘composite viewing 
transform’. The composite viewing transform is the transform that is actually 
used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 


Inquire World Coordinate 
Matrix 3 


inquire_world_coordinate_matrix_3 (array) 
float array[4][4]; /* array [row] [col] */ 




inquire_wor ld_coordinate_matrix_3 ( ) returns a 4 by 4 matrix con- 
taining the ‘world transform’ or modelling transform. This matrix is con- 
catenated with the ‘viewing transform’ to give the ‘composite viewing 
transform’. The composite viewing transform is the transform that is actually 
used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 


Inquire Inverse Composite 
Matrix (SunCore Extension) 


inquire_inverse_composite_inatrix (array) 
float array[4][4]; /* array [row] [col] */ 




SunCore uses the matrix inverse of the composite viewing transform internally 
for operations such as map_ndc_to_world ( ) . This matrix may at times be 
useful to the applications program. 


Inquire Viewing Control 
Parameters 


inqu i r e_vie wing_cont r o l_pa r ame t e r s ( windowc lip, 
frontclip, backclip, type) 

int *windowclip; /* TRUE if window clipping enabled */ 
int *frontclip; /* TRUE if front plane clipping enabled */ 
int *backclip; /* TRUE if back plane clipping enabled */ 
int *type; /* RIGHT or LEFT world coordinate system type */ 




inquire_viewing_control_parameters ( ) obtains the enabled status 
of clipping, and the type of world coordinates in use. 
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4.1. Retained Segment Attributes 

4.2. Retained Segment Operations 

Create a New Segment 

Close a Segment 

Delete a Retained Segment 

Rename a Retained Segment 

Delete All Retained Segments 

Inquire Retained Segment Surfaces 

Inquire Retained Segment Names 

Inquire Open Retained Segment 

4.3. Temporary or Non-Retained Segments 

Create Temporary Segment 

Close Temporary Segment 

Get Temporary Segment Status 

4.4. Saving and Restoring Segments on Disk 
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All output primitives for a graphical object are placed in a segment by SunCore 
on request from the application program. Each segment defines an image which 
is a view of the object and which is part of the picture displayed on the view sur- 
face. An application program describes an object by creating a segment, calling 
output primitive functions (the results of which are placed in the segment), and 
then closing the segment. 

There are two kinds of segments, namely: temporary segments and retained seg- 
ments. Retained segments have an image transformation type which specifies 
how they can be transformed. Retained segments can be made visible or invisi- 
ble, detectable (via the pick input function) or undetectable, highlighted, and may 
be transformed, depending on their type. 

Retained segments have names (actually numeric identifiers) so that by placing 
output primitives in such segments, the application programmer can selectively 
modify parts of the picture by deleting and recreating segments (which effec- 
tively replaces them) so that their images change. Retained segments are stored 
in the display list for later dynamic modification. 

Temporary segments are not saved in the display list, are only drawn once, and 
may not be modified dynamically. A new frame action deletes all portions of any 
temporary segments which have already been drawa 

In the same way that primitive attributes affect the output primitives, retained 
segment dynamic attributes affect the characteristics of retained segments. From 
now on, the term dynamic attributes means the dynamic attributes of retained 
segments. 

As well as being identified by the name of the retained segment into which they 
have been placed, output primitives may also be assigned a primitive attribute 
known as a pick identifier or pick-id. This means that within the single level of 
segmentation, another level of naming is provided. An example of the use of 
pick-id might be that all the character strings for (say) a menu could appear in a 
single segment, where each character string is assigned a different pick-id. Then 
when the user is using the mouse to select a specific item from the menu, the 
application program uses the PICK input function to find out which menu item 
was selected. 
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Retained segments have one static attribute and four dyncunic attributes. Attri- 
butes, and the means of setting diem and inquiring their values, are described in 
detail in Chapter 6. 

The only static attribute of retained segments is the image transformation type. 
This attribute can have one of five values: 

None 

The segment is a retained segment on which no transformations may be 
applied. 

Translatable 2D 

The segment is a retained segment which may be translated in 2D. 
Transformable 2D 

The segment is a retained segment which may be fully translated, scaled, 
and rotated, in 2D. 

Translatable 3D 

The segment is a retained segment which may be translated in 2 or 3D. 
Transformable 3D 

The segment is a retained segment which may be fully translated, scaled, 
and rotated, in 2 or 3D. 

SunCore sets image transformation type to the default value of NONE at initiali- 
zation time. 

The four dynamic attributes of retained segments are defined here. 

Visibility 

indicates whether the segment should have a visible image. There are only 
two values of this attribute, namely: TRUE and FALSE. 

SunCore sets the default value of visibility to TRUE at initialization time. 

Highlighting 

indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by blinking. There are only two values of the highlight- 
ing attribute, namely: TRUE and FALSE. When highlighting is turned on, 
the segment is blinked once. 

SunCore sets the default value of highlighting to FALSE at initialization 
time. 

Detectability 

indicates whether the retained segment can be detected by the pick device 
(mouse pointing device). See the await_pick () function. The values 
for the detectability attribute, are: 0 through 2,147,483,647. SunCore sets 
the default value of detectability to 0 at initialization time. 

Image Transformation 

indicates how the image of a retained segment, in NDC space, is scaled, 
rotated, or translated. A segment’s static image transformation type attribute 
limits the values which its image transformation attribute may have. See the 
set of functions called set_segTnent_image_ja:x() in Chapter 6. 
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4.2. Retained Segment 
Operations 



Create a New Segment 



Close a Segment 



Delete a Retained Segment 



SunCore sets the default value of image transformation to the identity 
transformation at initialization time. 

A retained segment is a form of storage for graphical primitives. This kind of 
segment remains for the duration of a SunCore application program unless it is 
deleted. After the program exits the contents of a retained segment are lost. 

create_retained_segment (segment_name) 

int segment_name; /* Segpment Identifier */ 

create_retained_segment ( ) creates a new, empty, open segment. The 
segment_name argument defines a segment number in the range 1 through 
2,147,483,647. 

The image transformation type for the newly created segment is obtained from 
the current attribute value for image_transf ormation_type. The 
dynamic attribute values for the newly created segment are obtained from the 
default values of the dynamic attributes for retained segments. 

Use the set_image_transf ormation_type ( ) function, before calling 
create_retained_segment ( ) , to specify whether the created segment is 
translatable or transformable. After calling 

create_retained_segment ( ) , the specified segment is said to be 
“open”. This means ftiat output primitives can now be called upon to add 
graphics primitives (lines, text, polygons, and so on) to this segment. 

Only one segment can be open at a time. 

□ The set of currently selected view surfaces is empty. 

□ The current viewing specification is inconsistent. 

□ There is already an open segment. 

□ A retained segment named segment_name already exists. 

□ The default value of image_trans formation is invalid for the current 
ima ge_t r an s f o rma t i o n_t y pe . 

close_retained_segment ( ) 

close_retained_segment ( ) closes the currently open segment. Dynamic 
segment attributes may be changed both before and after closing the segment. 

□ There is no open retained segment. 

delete_retained_segment (segment_name) 

int segment_name; /* Segment Identifier */ 

delete_retained_segment ( ) deletes a specifically named segment. The 
segment specified by the segment_name argument is deleted. If the segment 
being deleted is the currently open segment, it is closed before it is deleted. The 
deleted segment is erased from all view surfaces. 
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o There is no retained segment with the name segment_name. 

Rename a Retained Segment rename_retained_segment (segment_name, newname) 

int segment_name; /* Old Segment Identifier */ 

int newname; /* New Segment Identifier */ 

rename_retained_segment ( ) changes the name of a retained segment 
The segment whose identity is segment_name is renamed as newname, and 
this name must be used in any future references to that segment. The segment 
segment_name is no longer accessible. 

□ There is no retained segment with the name segment_name. 

□ There is an existing retained segment named new_name. 



Delete All Retained Segments delete_all_retained_segments ( ) 

delete_all_retained_segments 0 deletes all retained segments. All 
retained segments are deleted. If there is a currently open retained segment, it is 
closed before it is deleted. 



inquire_retained_segment_surf aces ( segment_name, 

array_size, view_surface_array, ruimber_of_surf aces) 
int segment_name; /* Name of Segment */ 

int array_size; /* Size of View Surface Array */ 

struct vwsurf view_surface_array [] ; 

/* Array of view surface names */ 
int *number_of_surf aces; 

/* Returned number of surfaces */ 

inquire_retained_segment_surf aces ( ) obtains the number and 
names of the view surfaces upon which this segment gets drawn. These view 
surfaces were ‘selected’ when the segment was created. The number of view sur- 
faces selected at the time the retained segment name given by segment name 
was created is copied into number_of_surf aces. The names of those sur- 
faces are copied into view_surf ace_array, where the array is an array of 
view surface names. array_size is specified by tte caller, and is the size of 
view_sur f ace_array. The view surface structure is defined in the 
<usercore . h> header file. 

If number_of_sur faces is greater fiian arrayjsize, only array_size 
view surface names are copied into \iew_surface_array. If array_size is less 
than or equal to zero, no names are returned. 

□ There is no retained segment with the name segment_name. 

inquire_retained_segment_names (array_size, 
name_array, number_of_segments) 
int array_size; /* Size of Array */ 

int name_array [] ; /* Segment Identifiers */ 

int *number_of_segments; /* Number of Segments */ 

inquire_retained_segment_names ( ) obtains a list of the retained seg- 
ments names. The name_array argument is an array which is to receive a list 



Inquire Retained Segment 
Names 



Inquire Retained Segment 
Surfaces 
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Inquire Open Retained 
Segment 



4.3. Temporary or Non- 
Retained Segments 



Create Temporary Segment 



Close Temporary Segment 



Get Temporary Segment 
Status 



4.4. Saving and Restoring 
Segments on Disk 



Save Segment on Disk File 
(SunCore Extension) 



of the existing retained segments, ar r ay s iz e specifies the number of ele- 
ments in name_array. The number _of_segments argument is returned to the 
caller, and is the number of existing retained segments. If the number of existing 
retained segments is greater than the size of the array, only array_size seg- 
ment names are copied into the array. If array_size is less than or equal to 
zero, no segment identifiers are returned. 

inquire_open_retain.ed._segment (segment_name) 
int *segment_name; /* Segment Name */ 

inquire_open_retained_segment ( ) obtains the name of the currently 
open retained segment. The name of the currently open retained segment (if 
there is one) is copied into the segment_name variable. If there is no currently 
open retained segment, segment_name is set to zero. 

Temporary segments are used for transient images. Temporary segments cannot 
be modified dynamically, and all portions of temporary segments which have 
already been drawn are deleted upon any new frame action. Primitives placed in 
temporary segments are not stored in the display list. 

create_temporary_segment () 

Great e_temporary_segment ( ) creates a new, empty, nonretained or tem- 
porary, segment. 

close_temporary_segment () 

close_temporary_segment ( ) closes the currently open temporary seg- 
ment. 

inquire_open_temporary_segment (open) 

int *open; /* Receives status of temporary segment */ 

inquire_open_temporary_segment ( ) determines whether there is a 
currently open temporary segment. The open argument receives the status of 
whether there is a currently open temporary segment: 

FALSE There is no currently open temporary segment. 

TRUE There is a currently open temporary segment. 



The two functions described in this section provide for saving segments on disk 
files and restoring segments from disk files. Only one segment is saved in a 
given file. 

save_segment (segment_name, filename) 

int segment_name; /* Name of segment to save */ 

char *filename; /* Pointer to a filename */ 

save_segment ( ) saves the named retained segment on a specified disk file. 
Saved primitives are in NDC space. Dynamic segment attributes are also saved. 
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Restore Segment from Disk 
File (SunCore Extension) 



restore_segment (segment_name, filename) 

int segment_name ; /* Name of segment to create */ 

char *filename; /* Pointer to a filename */ 

restore_segment ( ) restores the named retained segment from a specified 
disk file. A new segment is created and the segment from the disk file is copied 
into it. The segment is then closed. 
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Output Primitives 



Output Primitives serve to describe objects in the world coordinate system. 
When the output primitive functions are called, primitives are placed in the 
currently open segment via drawing commands which eventually produce line 
and character output. 

SunCore supports six kinds of output primitives, namely moves, lines and poly- 
lines, polygons, text, markers and polymarkers, and rasters. The table below 
summarizes these types of functions: 

Table 5-1 Summary of Output Primitive Functions 



Primitive 


Description 


Move 


primitives alter the value of the current position 
(described below). 


Line 


primitives describe lines in world coordinates. 


Polyline 


primitives describe sequences of connected lines in 
worid coordinates. 


Polygon 


primitives describe a closed polygon which will be filled 
with a color. The polygon primitives are a SunCore 
extension to the ACM Core specification. 


Text 


primitives describe character strings on the display. 


Marker 


primitives describe markers which are written on the 
display in a constant orientation, independent of any 
transformations which may be in effect. 


Polymarker 


primitives describe a sequence of markers which are 
written on the display in a constant orientation, indepen- 
dent of any transformations which may be in effect. 


Rasters 


primitive describes an array of one-bit or eight-bit pix- 
els. 



All primitive operations use world coordinates. Some of these operations affect 
the value known as the current position. The current position defines the current 
drawing location in the world coordinate system. SunCore maintains the value 
of the current position at all times. At initialization time, the current position is 
initialized to the origin of the world coordinate system. 
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In both 2 and 3D, coordinate positions can be specified in terms of absolute 
world coordinates, or coordinates can be specified relative to the current position. 

A segment must be open (see the create_xcco:_segment ( ) functions) 
before any output primitives may be used. A segment contains a set of output 
primitives which can subsequently be manipulated as a unit. 

An output primitive is processed as follows: 

1. The primitive is transformed to clipping coordinates using the composite 
viewing transform. This places the window boundaries at iunin=-32161, 
umox=+32767, vmin=-32161, and vmax=+'i2161. The front clipping plane is 
at z=0 and the back clipping plane is at z =+327 67. 

2. The primitive is then clipped to the boundaries just mentioned if window 
clipping is enabled. 

3. The output primitive is then ou^ut scaled to the viewport which is specified 
in NDC space. 

4. The resulting primitive is then copied to the display list or pseudo display 
file (PDF) if the open segment is a retained segment. 

5. Next, the primitive is transformed using the image transform which is an 
attribute of retained translatable or retained transformable segments. 

6. The output primitive is then clipped again to the viewport boundaries if out- 
put clipping is enabled. 

7. For each view surface which was selected when the segment was created, the 
primitive is then converted to physical device coordinates and drawn on the 
view surface. 

If a change is made to certain dynamic segment attributes of a retained segment, 
the primitives in that segment are recovered from the PDF and used to erase the 
segment (if necessary) and redraw the segment following steps 5 through 7 
above. The diagram below shows the above process in a graphical form. 
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Figure 5-1 Flofw Diagram of Output Primitive Processing 
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Output primitives are drawn with the static primitive attributes set by the primi- 
tive attribute functions (see Chapter 6). 

5.1. Moving the Current There are four functions for moving the current position. move_abs_2 ( ) and 

Position move_abs_3 ( ) change the current position to an absolute position in world 

coordinates, whereas move_rel_2 ( ) and move_r el_3 ( ) change the current 
position by a delta relative to the current position. 

Note that move_abs_2 ( ) and move_rel_2 ( ) are simply short forms of the 
corresponding 3D functions. The z coordinate of move_abs_2 ( ) is the z coor- 
dinate of the current position. The z delta of move_r el_2 ( ) is taken as zero. 

Move to Absolute 2D Position move_abs_2 (x, y) 

float X, y; /* x and y coordinates to move to */ 

move_abs_2 ( ) moves the current position to an absolute position. The 
current position is set to the values of x and y in 2D world coordinates. 
move_abs_2 ( ) only sets the current position; no drawing commands are out- 
put. 

Move to Absolute 3D Position move_abs_3 (x, y, z) 

float X, Yf z; /* x, and z coordinates to move to */ 

move_abs_3 ( ) moves the current position to an absolute position. The 
current position is set to the values of x, y, and z in 3D world coordinates. 
move_abs_3 ( ) only sets the current position; no drawing commands are out- 
put. 

Move to Relative 2D Position move_rel_2 (dx, dy) 

float dx, dy; /* x and y coordinate deltas */ 

move_rel_2 ( ) increments the current position by the values given. The 
current position is set to the value of current position plus dx and dy in 2D world 
coordinates. move_rel_2 ( ) only sets the current position; no drawing com- 
mands are output. 

Move to Relative 3D Position move_rel_3 (dx, dy, dz) 

float dx, dy, dz; /* x, y, and z coordinate deltas */ 

move_rel_3 { ) increments the current position by the values given. The 
current position is set to the value of current position plus dx, dy, and dz in 3D 
world coordinates. move_rel_3 ( ) only sets the current position; no drawing 
commands are output. 

5.2. Position Inquiry The position inquiry functions return the coordinates of the current position to 

Functions the caller. 

Inquire 2D Position inquire_current_position_2 (x, y) 

float *x, *y; 

inquire_current_position_2 ( ) returns the 2D world coordinates of 
the current position to the caller. 
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Inquire 3D Position 



5.3. Line Functions 



Describe Line in Absolute 2D 
Coordinates 



Describe Line in Absolute 3D 
Coordinates 



Describe Line in Relative 2D 
Coordinates 



Describe Line in Relative 3D 
Coordinates 



inquire_current_position_3 (x, y, z) 
float *x, *y, *z; 

inquire_current_position_3 ( ) returns the 3D world coordinates of 
the current position to the caller. 

The line functions draw lines on the currently selected SunCore view surfaces. 
Attributes of the line can be specified with additional calls to primitive attribute 
setting functions. 

The primitive attributes of line index, linestyle, linewidth, and pick_id are appli- 
cable for lines. 

□ There is no open segment. 

line_abs_2 (x, y) 
float x, y; 

line_abs_2 ( ) describes a line in 2D world coordinates. The line that 
line_abs_2 ( ) describes extends from the current position to the position 
specified by the x and y coordinates. 

The current position is updated to the coordinates specified by x and y. 

line_abs_3 (x, y, z) 
float X, Yr z; 

line_abs_3 ( ) describes a line in 3D world coordinates. The line that 
line_abs_3 ( ) describes extends from the current position to the position 
specified by the x, y, and z coordinates. 

The current position is updated to the coordinates specified by x, y, and z. 

line_rel_2 (dx, dy) 
float dx, dy; 

line_rel_2 ( ) describes a line in 2D world coordinates. The line that 
line_rel_2 ( ) describes extends from the current position to the position 
specified by the current position plus the dx and dy coordinates. The current 
position is updated by the deltas specified by dx and dy. 

line_rel_3 (dx, dy, dz) 
float dx, dy, dz; 

line_rel_3 ( ) describes a line in 3D world coordinates. The line that 
line_rel_3 ( ) describes extends from the current position to the position 
specified by the current position plus the dx, dy, and dz coordinates. 

The current position is updated by the deltas specified by dx, dy, and dz. 
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5.4. Polyline Functions 



Describe Line Sequence in 
Absolute 2D Coordinates 



Describe Line Sequence in 
Absolute 3D Coordinates 



Describe Line Sequence in 
Relative 2D Coordinates 



Describe Line Sequence in 
Relative 3D Coordinates 



The polyline functions describe connected sequences of lines. The first two or 
three arguments to a polyline function are arrays of the appropriate coordinates. 
Consider the polyline function: 

polyline_abs_3 (x_array, y_array, z_array, n) 
float x_array [ ] , y_array [ ] , z_array [ ] ; 

/* X, y, and z arrays */ 
int n; /* Number of coordinates */ 

The sequence of lines that these arrays of coordinates describe starts at the 
current position, then draws to: {x_array[0], y_array[0], z array [0]\ then runs 
through the intermediate array values and ends at {x_array[n-l], y_array[n-l], 
z_array[n-l ]) where n is the number of elements in each of die coordinate arrays. 
There are thus n lines in the figure described. 

□ The number of coordinates, n, is less than or equal to zero. 

□ There is no open segment. 

polyline_abs_2 (x_array, y_array, n) 

float x_array[], y_array[]; /* x and y coordinates */ 
int n; /* number of array elements */ 

polyline_abs_2 ( ) describes a line sequence in absolute 2D world coordi- 
nates. The current position is updated to the end of the last line drawn. 

polyline_abs_3 (x_array, y_array, z_array, n) 
float x_array[], y_array[], z_array[]; 

/* X, Y, and z arrays */ 
int n; /* number of elements */ 

polyline_abs_3 ( ) describes a line sequence in absolute 3D world coordi- 
nates. The current position is updated to the end of the last line drawn. 

polyline_rel_2 (dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y delta arrays */ 
int n; /* number of array elements */ 

polyline_rel_2 ( ) describes a line sequence in relative 2D world coordi- 
nates. The sequence of lines that this function describe starts at the current posi- 
tion, moves to: current position + dx array [0], ( dy array [0]) then draws to: 
current position + dx_array [0], ( dy_array [0]) + dx_array [1], ( dy_array [1]) 
and so on. The current position is updated to the end of the last line drawn. 

polyline_rel_3 (dx_array, dy_array, dz_array, n) 
float dx_array[], dy_array[], dz_array[] ; 

/* X, Yr and z delta arrays */ 
int n; /* number of elements */ 

polyline_rel_3 { ) describes a line sequence in relative 3D world coordi- 
nates. The sequence of lines diat this function describe starts at the current posi- 
tion, moves to: current position + dx array [0], ( dy array [0], dz array [0]) 
then draws to: current position + (dx_array[0] , dy_array[0], dz_array[0]) + 
(dx_array[lj, dy_array[l], dz_array[l]) and so on. The current position is 
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updated to the end of the last line drawn. 

5.5. Text Functions The functions described in the next section describe the text facilities available in 

SunCore. The inquiry functions that follow can be used to determine characteris- 
tics of text. 

text (string) ; 
char *string; 

text ( ) draws a character string in world coordinates. The character string 
specified by string is drawn from the current position. The current position is 
unchanged. The font, size, orientation, and so on, are set by calls to the set prim- 
itive attribute functions. 

□ There is no open segment. 

o The character string contains one or more characters which cannot be drawn. 

o The vectors that the current charpath and charup attributes describe are paral- 
lel. 

5.6. Text Inquiry Functions Text inquiry functions obtain the length that a character string would extend, in 

world coordinates, if the character string were actually drawn according to the 
current text primitive attributes. 

□ inquire_text_extent_2 ( ) was used to obtain the current position 
when inquir e_text_extent_3 ( ) should have been used in order to 
avoid loss of information. 

□ The character string contains one or more characters which carmot be drawn. 

□ The vectors that the current charpath and charup attributes describe are paral- 
lel. 

Inquire Text Extent 2 inquire_text_extent_2 (string, dx, dy) 

char *string; 
float *dx, *dy; 

inquire_text_extent_2 ( ) returns the extent of the character string 
specified by string, if the character string were drawn, unjustified, from the 
current position. The extent is returned in dx and dy in world coordinates relative 
to the current position. 

The specified character string, and the values of the primitive attributes /ont, 
charup, charsize, charpath, charspace, and charprecision are used to calculate 
the vector which represents the extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful 
values if charprecision is CHARACTER. 

Inquire Text Extent 3 inquire_text_extent_3 (string, dx, dy, dz) 

char *string; 
float *dx, *dy, *dz; 

inquire_text_extent_3 ( ) obtains the 3D extent, in world coordinates, of 
sun Revision A, of 9 May 1988 
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the specified character string. inquire_text_extent_3 ( ) returns the 
extent of the character string specified by string, if the character string were 
drawn, unjustified, from the current position. The extent is returned in dx, dy, 
and dz in world coordinates relative to the current position. 

The specified character string, and the values of the primitive attributes 
charup, charsize, charpath, charspace, and charprecision are used to calculate 
the vector which represents the extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful 
values if charprecision is CHARACTER. 

5.7. Marker Functions The marker functions place a character at a specific location on the display. The 

polymarker functions place a character at a sequence of locations on the display. 

The marker character is any printable ASCII character, and is the value of tte 
marker_symbol primitive attribute. The marker_symbol primitive attri- 
bute is set by the set_marker_symbol ( ) function described in Chapter 6. 

The markers are placed on the display without any of the rotations, translations, 
or scaling which is applied to text strings. Markers use the default orientation 
attributes. 

□ There is no open segment. 



Plot Marker at Absolute 2D 
Coordinates 



Plot Marker at Absolute 3D 
Coordinates 



Plot Marker at Relative 2D 
Coordinates 



marker_abs_2 (x, y) 

float Xf y; /* Absolute x and y Coordinates */ 

marker_abs_2 ( ) plots a marker at specified absolute 2D world coordinates. 
marker_abs_2 ( ) plots the marker at the absolute 2D coordinates specified by 
the X and y arguments. The current position is updated to be this point. 

marker_abs_3 (x, y, z) 

float X, y, z; /* Absolute x, y, and z Coordinates */ 

marker_abs_3 ( ) plots a marker at specified absolute 3D world coordinates. 
marker_abs_3 ( ) plots the marker at the absolute 3D coordinates specified by 
the X, y, and z arguments. The current position is updated to be this point. 

marker_rel_2 (dx, dy) 

float dx, dy; /* x and y Coordinate Deltas */ 

marker_rel_2 ( ) plots the marker at the position relative to the current posi- 
tion, specified by the deltas dx and dy. The current position is updated to be this 
point. 



Plot Marker at Relative 3D marker_rel_3 (dx, dy, dz) 

Coordinates float dx, dy, dz; /* x, y, and z Coordinate Deltas */ 

marker_rel_3 ( ) plots a marker at a specified relative 3D position. 
marker_rel_3 ( ) plots the marker at the position relative to the current posi- 
tion, specified by the deltas dx, dy, and dz. The current position is updated to be 
this point. 
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Plot Marker Sequence at 
Absolute 2D Coordinates 



Plot Marker Sequence at 
Absolute 3D Coordinates 



Plot Marker Sequence at 
Relative 2D Coordinates 



Plot Marker Sequence at 
Relative 3D Coordinates 



5.8. 3D Polygon Shading 
Parameters (SunCore 
Extension) 



polymarker_abs_2 (x_array, y_array, n) 

float x_array[], y_array[]; /* Absolute x and y */ 

int n; /* Niomber of Coordinates */ 

polymarker_abs_2 ( ) plots a sequence of markers at specified absolute 2D 
positions. polymarker_abs_2 ( ) plots a sequence of markers at the absolute 
positions specified by the x_array and y array arguments, n specifies the 
number of coordinates in the arrays. The current position is updated to be the 
last point. 

polymarker_abs_3 (x_array, y_array, z_array, n) 
float x_array[], y_array[], z_array[]; 

/* Absolute X, y, and z */ 
int n; /* Number of Coordinates */ 

polymarker_abs_3 ( ) plots a sequence of markers at specified absolute 3D 
positions. polymarker_abs_3 ( ) plots a sequence of markers at the absolute 
positions specified by the x array, y array, and z array arguments. The number 
of coordinates in tte array is given by the n argument. The current position is 
updated to be the last point 

polymarker_rel_2 (dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y Deltas */ 

int n; /* Number of Coordinates */ 

polymarker_rel_2 ( ) plots a sequence of markers at specified relative 2D 
positions. polymarker_rel_2 ( ) plots a sequence of markers at the posi- 
tions relative to the current position, specified by the deltas dx array and 
dy array. The number of deltas in the arrays is specified by n. The current posi- 
tion is updated to be the last point. 

polymarker_rel_3 (dx_array, dy_array, dz_array, n) 
float dx_array [ ] , dy_array [ ] , dz_array [ ] ; 

/* X, y, and z Deltas */ 
int n; /* Number of Coordinates */ 

polymarker_rel_3 ( ) plots a sequence of markers at specified relative 3D 
positions. polymarker_rel_3 ( ) plots a sequence of markers at the posi- 
tions relative to the current position, specified by the deltas dx array, dy_array, 
and dz array. The number of deltas in the arrays is specified by n. The current 
position is updated to be the last point. 

When drawing 3D polygons on the Sun color displays, several shading options 
are available. The functions described in this section provide shading control. 
These shading parameters may be changed at any time and are not stored in the 
display list. Therefore a segment may be drawn with fast shading at one time, 
and then drawn again later with smooth shading. 
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Set Shading Parameters set_shading_jparameters (ambient, diffuse, 

specular, flood, bump, hue, style) 
float ambient; /* percent background light */ 
float diffuse; /* percent diffuse reflection */ 
float specular; /* percent specular reflection */ 
float flood; /* percent flood lighting */ 
float bump; /* specular power 2 . . 9 */ 
int hue; /* color index range to generate */ 

/* 0 = 0 . . 255, 1=0 . . 63 */ 

/* 2 = 64 .. 127, 3 = 128 .. 191 */ 

/* 4 = 192 . . 255 */ 

int style; /* Type of surface shading to do: */ 

/* CONSTANT, GOURAUD, PHONG */ 

set_shading_parameter s ( ) specifies the parameters for rendering 3D 
polygons on the color display. See set_polygon_interior_style () for 
the ways in which these shading parameters are used. CONSTANT style shading 
gives constant intensity over the polygon using the color set by 
set_f ill_index ( ) . GOURAUD style shading linearly interpolates between 
vertices where the intensity at each vertex is set by the 

set_vertex_indices () function. PHONG style shading produces smooth 
shading using the other parameters (only with convex polygons). 

The equation used for PHONG style shading is: 

pixelshade =ambient+diffuse (L *N y\-specular {H *N -(flood* z ) 

where L is the direction vector of the light source, N is the surface normal vector, 
H is a vector which is the average of L and E (the eye direction vector), and z is 
depth in NDC. 

Here are some useful sets of PHONG parameters: 

Table 5-2 2 Useful PHONG Parameters 



Parameter 


Value 


Value 


ambient 


0.05 


0.05 


diffuse 


0.94 


0.74 


specular 


0.0 


0.20 


flood 


0.0 


0.0 


bump 


0.0 


7.0 


hue 


0 


0 



Specify Direction of Light set_light_direction (dx, dy, dz) 

Source float dx, dy, dz; 

set_light_direct ion ( ) specifies the direction of the light source from 
the object. This assumes NDC space where the direction from object to viewer is 
always {0.0, 0.0, -1.0}. Hence, to place the light source at the viewer, the light 
direction is (0.0, 0.0, —1.0). The light direction vector is only used if the shading 
style is GOURAUD or PHONG. A useful light direction is (-0.2, 0.2, -1.0). 
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Set Vertex Normals 



Set Vertex Indices 



set_vertex_nonnals (xlist, ylist, zlist, n) 
float xlist [], ylist[], zlist[]; 
int n ; 

set_vertex_normals ( ) sets the surface normal vectors for each vertex of 
the subsequent 3D polygon primitives (polygonabs_3 ( ) or polygon- 
re 1_3 ( ) ). These normals are used for PHONG style shading. For GOURAUD 
style shading, use set_vertex_indices ( ) . The number of elements in the 
list, n, must be equal to the number of vertices in the subsequent call to 
polygoruxc_3 ( ) . 

set_vertex_indices (color_index_list , n) 
int color_index_list [ ] ; 
int n; 

set_vertex_indices ( ) specifies a color index for each vertex of the next 
polygonxxx_3 ( ) primitive. GOURAUD shading linearly interpolates these 
color indices for smooth shading in the interior of the polygon. The number of 
elements in the list, n, must be equal to the number of vertices in the subsequent 
call to polygonxcc_3 ( ) . 

Note: If the hue argument to set_shading_j>arameters ( ) is 0, then 
color _index_list is an index into the predefined colormap. If hue is 1, then the 
first 64 values in the predefined colormap are interpolated into color index list. 
If hue is 2, then the second 64 values are used, and so on. 



Set Z Buffer Cut set_zbuf fer_cut (surf ace_name, xlist, zlist, n) 

struct vwsurf *surface_name; /* See Appendix B */ 
float xlist [], zlist []; 
int n ; 

set_zbuf f er_cut ( ) specifies a cutaway view of 3D polygon objects when 
hidden surfaces are being removed. set_zbuf fer_cut ( ) specifies an array 
of depths in NDC space. Any parts of objects which are closer to the viewer than 
this piecewise-linear function are clipped away. 

Note: this function has no effect on Graphics Processor view surfaces, i.e. 
gpldd or gplpixwindd. xlist is assumed to be monotonically increasing. 
This function specifies a piecewise-linear cutaway threshold in the z coordinate, 
which, given any x coordinate, is constant in y. The default cutaway depth is 0 
for all values of x. Values of x less than xlist [0] or greater than xlist [n - 1] will 
have the default depth. The view surface must have been initialized with the hid- 
den flag on. 

5.9. Polygon Functions The polygon functions are a SunCore extension to the ACM Core specification. 

(SunCore Extension) The polygon functions describe connected sequences of lines which form closed 

figures. The polygons are filled in with color as specified by the 
set_f ill index ( ) primitive attribute, or are shaded according to the 
current shading parameters, depending on the polygoninterior_style 
primitive attribute. Only polygons created by the 3D polygon functions may be 
shaded. 
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The first two or three arguments to a polygon function are arrays of the appropri- 
ate coordinates. Consider the polygon function; 

polygon_abs_3 (x_array, y_array, z_array, n) 
float x_array [ ] , y_array [ ] , z_array [ ] ; 

/* X, y, and z coordinates */ 
int n; /* Nioinber of coordinates */ 

The bounding sequence of edges that these arrays of coordinates describe pass 
from die first point x_array[0],{ y_array[0], z_array[0]), then runs througji the 
intermediate array values to {x_array[n-l]^y_array[n-l], z_array[n-l]) and then 
back to the first point, n is the number of elements in each of the coordinate 
arrays. There are thus n sides in the figure described. 

Note that the polygon functions describe a closed figure. The last coordinate in 
the array of points is coimected to the first point. 

□ The number of coordinates, n, is less than or equal to two. 

□ There is no open segment. 



Describe Polygon in Absolute polygon_abs_2 (x_array, y_array, n) 

2D Coordinates float x_array[], y_array[]; /* x and y coordinates */ 

int n; /* number of array elements */ 

polygon_abs_2 ( ) describes a polygon in absolute 2D world coordinates. 
The current position is set to the first point. 



polygon_abs_3 (x_array, y_array, z_array, n) 
float x_array[], y_array[], z_array[]; 

/* X, Y, and z coordinates */ 
int n; /* number of array elements */ 

polygon_abs_3 ( ) describes a polygon in absolute 3D world coordinates. 
The current position is set to the first point. 

Describe Polygon in Relative polygon_rel_2 (dx array, dy_array, n) 

2D Coordinates float dx_array[], dy_array[]; /* x and y deltas */ 

int n; /* number of array elements */ 

polygon_rel_2 ( ) describes a polygon in relative 2D world coordinates. 
The first array value specifies a displacement from the current position; remain- 
ing array values specify displacements from the preceding point The current 
position is set to the first point. 



Describe Polygon in Absolute 
3D Coordinates 



Describe Polygon in Relative 
3D Coordinates 



polygon_rel_3 ( ) describes a polygon in relative 3D world coordinates. 
The first array value specifies a displacement from the current position; remain- 
ing array values specify displacements from the preceding point The current 
position is set to the first point. 



polygon_rel_3 (dx_array, dy_array, dz_array, n) 
float dx_array [ ] , dy_array [ ] , dz_array [ ] ; 

/* X, y, and z deltas */ 
int n; /* number of array elements */ 
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5.10. Raster Primitive The raster primitive functions described in the following sections allow the Sun- 

Functions (SunCore Core application program to access and manipulate rectangular arrays of pixels. 
Extension) Both monochrome and color frame raster primitives are supported. These func- 

tions are not a part of the standard Core system. 

Raster Output Primitive put raster (raster) 

struct suncore_raster *raster; 

put_raster ( ) draws a rectangular 1-bit or 8-bit deep raster and enters it into 
the current segment. The raster may not be used in transformable segments, 
because rasters cannot be scaled or rotated in the current release of SunCore. A 
raster primitive may, however, be picked or dragged if it is entered in a translat- 
able segment. The current position is at the lower left-hand comer of the raster. 

Note that put_raster ( ) is device dependent in that it is written to the right 
and upward from the current position a specified number of PIXELS in height and 
width. The current position is unchanged. 

Here is the definition of the suncore_r aster stmcture. 

struct suncore_raster { 
int width; 
int height; 
int depth; 
short *bits; 

}; 

The depth parameter can be 1 or 8 bits per pixel. 

The bits of the raster are stored in the following order iordepth = 1 : The first 
word is the upper left 16 horizontal bits, with the high order bit being the left- 
most bit The first {width + 15)/ 16 words comprise the top row of the rectangle. 
The number of words of storage that bits points to is: 

( (width+15) / 16) * height 

for depth = 1. 

Rasters of depth = 8 are stored as successive bytes in row order. The number of 
bytes that bits points to is: 

width * height 

for depth = 8. 

If a 1-bit deep raster is written to a color view surface, ‘0’ bits select the back- 
ground color and ‘ 1 ’ bits select the color specified by the fill index primitive attri- 
bute. 

Note that output clipping is always done on raster primitives. 
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get_raster (surf ace_name, xmin, xmax, 
ymin, ymax, x, y, raster) 
struct vwsurf *surf ace_name; /* See Appendix B */ 
float xmin, ymin, xmax, ymax; 

/* Region of NDC space to read */ 
int X, y; /* starting point pixel offsets 
in raster relative top left */ 
struct suncore_raster ^raster; /* Returned Raster */ 

get r aster ( ) reads a specified region of the monochrome or color frame 
buffer into a storage area. get_raster ( ) requires an area of memory large 
enough to hold the raster region that it returns. It is the user’s responsibility to 
allocate this storage area before calling get_raster ( ) . The 
size_raster ( ) and allocate_raster ( ) functions may be used to do 
this: 

size_raster (surface_name, xmin, xmax, ymin, ymax, Sraster) ; 
allocate_raster (&raster) ; 
if (raster. bits == NULL) 

error case - the raster could not be allocated 

else 

continue with the processing 

To free the area when finished with the raster, call the free_r aster ( ) func- 
tion: 

f ree_raster (Sraster) ; 

Hence, a large raster may be allocated and then portions of it filled with data 
using get_r aster ( ) with various jc,.I y offsets, in pixel coordinates from die 
top left hand comer of the raster. 

Set Size of Raster in NDC size_raster (surface_name, xmin, xmax, ymin, ymax, raster) 

struct vwsurf *surf ace_name; 
float xmin, xmax, ymin, ymax; 
struct suncore_raster *raster; 

size_raster ( ) returns the raster with the pixel coordinates width, height, 
and depth, for a specified region of NDC space and a specified view surface. On 
return, raster . bits is set to NULL. 

Allocate Space for a Raster allocate_raster (raster) 

struct suncore_raster *raster; 

Given a raster whose width, height, and depth fields were filled by the 
size_raster ( ) function (described above), allocate_raster ( ) allo- 
cates the memory required for that raster and sets the raster . bits pointer, 
allocateraster () returns a NULL pointer value in raster .bits if it is 
unable to obtain enough memory for the raster stmcture. 

Free Space of a Raster free raster (raster) 

struct suncore raster *raster; 



Read Raster from 
Monochrome or Color Frame 
Buffer 
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f ree_raster ( ) frees the memory used by a specified raster, if 
raster .bits is not NULL. 

raster_to_file (raster, map, fd, replicate) 
struct suncore_raster * raster; 
struct { 

int type; /* 1 for RGB color table */ 
int nbytes; /* 3 times niamber 
of color table elements */ 
char *data; /* ptr to nbytes/3 red, 
blue, and green bytes */ 

} *map ; 

int fd; /*standard file descriptor for C programs */ 

/* FORTRAN logical unit number 
for FORTRAN programs */ 

/* Pascal file variable for Pascal programs */ 
int replicate; /* magnification factor */ 

raster_to_f ile ( ) copies a raster to a disk file in Sun’s standard raster file 
format. If map . nbytes = 0, no color map data will be written. This would 
normally be the case for rasters copied from the bitmap display. 

The replicate parameter specifies whether the raster should be magnified on 
transmission to the file. The raster is transmitted without magnification if andre- 
plicate= 1, pixel-replication zoom for a factor of 2 magnification if replicate^ 2. 

Note: The colormap information provided to raster to f ile ( ) includes 
integer color values in the range 0-255. SunCore normally takes floating point 
color values in the range 0-1.0. 

The format of the generated disk file can be found in the include file in 
<rasterf ile . h>. Disk raster files can be printed on a raster addressable hard 
copy device by using the Ipr(l) command with the — v option. 

Get a Raster from a Disk File f ile to raster (fd, raster, map) 

int fd; 

/* standard file descriptor for C programs */ 

/* Fortran logical unit number for Fortran programs */ 

/* Pascal file variable for Pascal programs */ 
struct suncore_raster *raster; 
struct { 

int type; /* 1 for RGB color table */ 
int nbytes; /* 3 times number 
of color table elements */ 
char *data; /* ptr to nbytes/3 red, 
blue, and green bytes */ 

} *map; 

f ile_to_raster ( ) allocates enough memory for a raster stored on a disk 
file, then fills in all fields of the raster and map structures. Note that this function 
frees map . data, unless data is NULL, and allocates map . data each time it is 
called — therefore map . data is only valid in the last call to this function. The 
raster .bits field is set to NULL if there is not enough room to allocate the 



Copy a Raster to a Disk 
Raster File 
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raster. 

The format of the disk file can be found in the include file in 
<rasterf ile .h>. 
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6.1. Primitive Static 
Attributes 



Attributes in SunCore specify general characteristics for segments and for output 
primitives. 

There are two major divisions of attributes. One set of attributes is called seg- 
ment attributes and applies only to retained segments. The other set is called 
primitive attributes and applies only to output primitives. There are no attributes 
which apply to both retained segments and to output primitives. 

Attributes are further subdivided into static and dynamic. Static attributes 
specify characteristics of retained segments or output primitives which apply for 
the entire lifetime of diose objects. Dynamic attributes specify characteristics of 
segments which can change during the lifetime of those segments. Static primi- 
tive attributes are stored in the display list so that subsequent manipulation of a 
segment is performed with the appropriate attributes. 

The list below defines the primitive static attribute values. 
line index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for line and polyline output primi- 
tives. Index value 0 corresponds to the background color. For lines and 
polylines on monochrome displays, a non- zero line index gives black lines 
on a white background. SunCore initializes line index to 1. The range of 
possible values is 0 to 255. 

fill index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for polygon and raster output primi- 
tives. Index value 0 corresponds to the background color. For monochrome 
displays, the values form a set of definitions for texture, described later. 
SunCore initializes fill index to 1. The range of possible values is 0 to 255. 

text index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for markers and text Index value 0 
corresponds to the background color. For text and markers on monochrome 
displays, a non- zero rexrindex" gives black on a white background. SunCore 
initializes text index to 1. The range of possible values is 0 to 255. 
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linestyle 

is an int value which controls the appearance of lines drawn. Linestyle can 
assume the values: 

SOLID Solid lines, 

DOTTED Dotted lines, 

DASHED Dashed lines, 

DOTDASHED 

Dotdashed lines. 

The definitions of these constants can be found in <usercore . h>. Sun- 
Core sets linestyle to SOLID at initialization time. 

polygon interior style 

is an int value which controls the interior filling style for polygons. 
polygon interior style can have die values: 

PLAIN Solid color polygon 

SHADED Shading style is set dynamically by 

set_shading_j>arameter s ( ) . Only 3D polygons may be 
shaded. 

SunCore sets polygon interior style to PLAIN at initialization time. 
polygon edge style 

is not implemented in the current release of SunCore. 
linewidth 

is a float value which describes, in world coordinates, the width of drawn 
lines. SunCore sets linewidth to 0.0 (the minimum) at initialization time. 



pen 

is an int value which is passed to the device driver to select a particular 
device dependent pen. SunCore initializes pen to 0. 

font 

is an int value which determines the character font in which text will be 
written. Font can assume the following values (for 
c/w/prec wzort=CH ARACTER) : 

ROMAN If charprecision=^STKTi^Gy this gives a large raster font. 

GREEK If charprecision=STKJLiQ, this gives the default raster font. 

SCRIPT If charprecision=STR5FlGy this gives a small raster font. 

OLDENGLISH If charprecision=STKTtlG, this is equivalent to a bold ver- 
sion of GREEK. 

STICK If cluirprecision=STKfiiG, this is equivalent to a medium 

sized ROMAN raster font. 

SYMBOLS Currentiy holds some electronics symbols (character values 
32 through 47). If c/ia/ 7 ?rccwzon=STRING, this is 
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equivalent to a bold version of STICK. 

SunCore sets/onr to STICK at initialization time. 
charsize 

is a pair of float values which determine the size of characters, in world 
coordinates. SunCore sets the default character width to 1 1.0 and the default 
character height to 1 1.0 at initialization time. 

charup 

attribute consists of three float values which represent a vector giving the 
direction of ‘up’ for characters: 

(dx_charup, dy_charup, dz_charup) 

in world coordinates. Usually, charup is normal to charpath. SunCore 
establishes the default as a vector in the positive y direction (0.0, 1.0, 0.0) at 
initialization time. 

charpath 

consists of three float values which represent a vector: 

(dx_charpath, dy_charpath, dz_charpath) 

that determines the direction, in world coordinates, in which character 
strings will extend. SunCore sets the charpath attribute to (1.0, 0.0, 0.0) at 
initialization time. 

charspace 

is a single float value specifying the space, in world coordinates, which 
should be inserted between characters in a text string. SunCore establishes 
charspace with the value 0.0 at initialization time. 

charjust 

is not implemented in the current release of SunCore. 
charprecision 

is an int value which controls the quality of the text drawing operation. 
Charprecision can have the values: 

STRING Fast raster fonts, fixed size, and fixed orientation. 

CHARACTER Hershey vector fonts. 
marker symbol 

determines the character which is plotted on the displays by the marker and 
polymarker functions described in Chapter 5. Any printable ASCII character 
can be used as the marker character. 

Note: The ACM Core specifies that the integer values 1 through 5 represent 
specific characters. SunCore does not implement this feature. 

pick id 

is an int value identifying the next output primitive. The input primitives 
use this number for user interaction with segments and primitives within 
segments. 
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rasterop 

specifies the rasterop used when writing to the display. It can be one of: 

NORMAL Source value is written to the display. 

XORROP Source value is exclusive or’ed with the value already in the 
display before being written to the display. 

ORROP Source value is or’ed with the value already in the display 
before being written to the display. 

This attribute is ignored if set_drag ( ) was specified as TRUE. 

The functions listed in the subsections below each set the specified attribute 
value for the indicated primitive attribute. 

□ One or more of the attribute values is incorrect. 

□ No character orientation can be established because dx charpath, 
dyjcharpath, and dzjcharpath are all zero. 

□ No character up direction can be established because dx charup, dy champ, 
and dz charup are all zero. 

6.2. Using Texture for When a monochrome display is used, the^// index attribute is used to determine 

Color Attributes on the how a region of the screen is textured when using the polygon output primitives. 

Monochrome Display Texturing is done in terms of 16 x 16 pixel regions of the screen. There are 16 

rows of 16 pixels each. The fill index attribute selects an entry from each of three 
arrays of float values in the range 0.0 through 1.0, representing red, green, and 
blue. In the case of the monochrome display, each of these three float 
numbers is converted to an integer between 0 and 255. Each of the 8-bit 
numbers is divided into two four-bit quantities, which we can call A and B. 



Table 6- 1 Structure of a Fill-Index Value 



Red 


Green 


Blue 


Select Select 
B A 


Length Length 
B A 


Rotate Rotate 
B A 



Select A and Select B are four-bit values which are used to select an A pattern 
and a B pattern out of the table of numbers shown below. 
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Table 6-2 Texture Selection Values 



Four-Bit Value 


Hexadecimal Pattern 


Binary Pattern 


0 


0000 


0000000000000000 


1 


8000 


1000000000000000 


2 


8080 


1000000010000000 


3 


8410 


1000010000010000 


4 


8888 


1000100010001000 


5 


9124 


1001000100100100 


6 


9494 


1001010010010100 


7 


A552 


1010010101010010 


8 


AAAA 


1010101010101010 


9 


EB6E 


1110101101101110 


10 


DDDD 


1101110111011101 


11 


F7F7 


1111011111110111 


12 


FFFF 


1111111111111111 


13 


E3E3 


1110001111100011 


14 


FFOO 


1111111100000000 


15 


OOFF 


0000000011111111 



The patterns are then laid down in the texture field, pixels, as described in the 
pseudo code below. 

let X = y = Pattern A 
for index = 0 to Length A - 1 
pixels [index] = x | y 

if Rotate A & 1 then rotate x one bit right 

if Rotate A & 2 then rotate x one bit left 

if Rotate A & 4 then rotate y one bit right 

if Rotate A & 8 then rotate y one bit left 

let X = y = Pattern B 

for index = Length A to Length A + Length B - 1 
pixels [index] = x | y 

if Rotate B & 1 then rotate x one bit right 

if Rotate B & 2 then rotate x one bit left 

if Rotate B & 4 then rotate y one bit right 

if Rotate B & 8 then rotate y one bit left 

If the value of 

length A + length B 

is less than 16, the processes described above are repeated as many times as 
required to fill the 16 line region. 

The above encoding provides for an enormous number of textures. Here are a 
few of the useful ones. 
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Table 6-3 Useful Texture Selection Values 



Texture 


Red 


Green 


Blue 


Hatched Left 


0.1334 


0.5020 


0.3529 


Hatched Right 


0.1334 


0.5020 


0.6471 


Wallpaper 


0.4667 


0.5334 


0.2118 


Black 


0.0000 


0.2667 


0.3882 


White 


0.2667 


0.4001 


0.8001 


Wavy Lines 


0.3334 


0.4001 


0.1334 


Grey Tone 


0.5334 


0.4001 


0.5334 


Cross Hatched 


0.5334 


0.4001 


0.1334 



Assign Colors to Indices define_color_indices (surface_name, il, 12, 

red_array, green_array, blue_array) 
struct vwsurf *surface_name; /* See appendix B */ 
int 11, 12; /* indices range from 0 through 255 */ 
float red_array[], green_array [] , blue_array [] ; 

def ine_color_indices ( ) defines entries in the color lookup table of a 
view surface. The three arrays provide the values for red, green, and blue respec- 
tively. The value of each element in the color arrays is in the range 0.0 through 
1.0. The function defines all the indices in the color index table between il and 
i2 inclusive, using the first i2~il+l elements from each of the three arrays. 

Subsequent calls to the set_xxx_index ( ) function selects a color from the 
lookup table to use as a color attribute. 

Location 0 in the color tables is the background color for the view surface. For 
the monochrome displays, lines, text, and markers are drawn black for any color 
index other than 0. 

SunCore initializes the lookup table for monochrome view surfaces such that for 
the fth entry, red[/] = /, green[i] = 255-i, and blueft] = i. SunCore initializes 
color view surfaces which have a full 256-element lookup table such that entry 0 
is gray, entry 1 is black, entries 2 through 63 contain an intensity ramp in red, 
entries 64 through 127 contain an intensity ramp in green, entries 128 through 
191 contain an intensity ramp in blue, and entries 192 through 255 contain an 
intensity ramp in yellow (red+green). See appendix B for details of color view 
surfaces with fewer than 256 entries in the lookup table. 

Note: If the SunCore application is run in the SunView environment, 
vwsurf . cmapname and vwsurf . cmapsize must be defined in order to 
cooperate with colormap sharing provided by SunView. 

Select a Line Color Attribute set line index ( index) 

int index; /* range 0 through 255 */ 

set_line_index { ) selects a color by providing an index into the tables 
defined by the def ine_color_indices ( ) function. This color attribute is 
applied to subsequent line and polyline output primitives. 
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Select a Polygon and Raster set f ili index ( index) 

Color int index; /* range 0 through 255 */ 

setf iliindex ( ) selects a color by providing an index into the tables 
defined by the def ine_color_indices ( ) function. This color attribute is 
applied to subsequent polygon and raster output primitives. 

Select a Text and Marker set_text_index { index) 

int index; /* range 0 through 255 */ 

set_text_index { ) selects a color by providing an index into the tables 
defined by the def ine_color_indices ( ) function. This color attribute is 
applied to subsequent text and marker output primitives. 

set_linewidth (linewidth) 
float linewidth; /* unit of width 
is 1 percent of NDC space */ 

set_linewidth ( ) specifies the linewidth attribute for the output primitives. 
SunCore initializes linewidth to 0.0, which results in a one pixel wide line. 

If XOR’ing is enabled (via the set_rasterop ( ) or set_drag ( ) func- 
tions), lines whose pixel width is greater than one may partially overwrite them- 
selves, resulting in poorly drawn wide lines. Redrawing the lines with XOR’ing 
off will draw the lines correctly (until this problem is fixed). 

set_linestyle (linestyle) 
int linestyle; /* SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 

set_line Style ( ) specifies the linestyle attribute for output primitives. Sun- 
Core initializes linestyle to SOLID, 

set_polygon_interior_style (style) 
int style; /* PLAIN, SHADED */ 

set_jpolygon_interior_style ( ) specifies the method of filling for 
polygons. If the filling method is SHADED, polygons are shaded according to the 
parameters set by the set_shading_parameters ( ) function. Only 3D 
polygons may be shaded. 

Set Polygon Edge Style (No set_polygon_edge_style (style) 

Effect) int style; /* SOLID, INTERIOR */ 

set_polygon_edge_style ( ) specifies the method of drawing the edges of 
a polygon. This function has no effect in the current release of SunCore. 

Set Font set_font (font) 

int font; /* ROMAN, GREEK, SCRIPT */ 

/* OLDENGLISH, STICK, SYMBOLS */ 

set_f ont ( ) specifies the/<?nt attribute for the output primitives. SunCore ini- 
tializes font to STICK. If the charprecision attribute is set to STRING, ROMAN 



Select Plain or Shaded 
Polygons 



Color 



Set Linewidth 



Set Linestyle 
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gives a small Roman font, GREEK gives a stick figure font, SCRIPT gives a tiny 
stick figure font, OLDENGLISH gives a bold version of GREEK, STICK gives a 
medium sized ROMAN raster font, and SYMBOLS gives a bold version of STICK. 
The STRING precision fonts are ‘raster’ fonts and are not scalable or rotatable, 
hence they are in pixel coordinates and are larger on the color surface than on the 
monochrome bitmap display. 

Select a Device Dependent Pen set _pen (pen) 

(no effect) int pen; 

This function has no effect on the standard SunCore view surfaces. 

Set Character Size set_charsize (charwidth, charheight) 

float charwidth, charheight; 

set_charsize ( ) specifies the charsize attribute for the text output primitive, 
in world coordinates. If the charprecision attribute is set to STRING, 
set_char size ( ) has no effect, except to control the target extent of the text 
for the await_pick ( ) function. If the charprecision attribute is set to CHAR- 
ACTER, set_charsize { ) sets the average size of a character, given that each 
character has its own size. 

Define Character Spacing for set_char space (charspace) 

Output Primitives float charspace; 

set_char space ( ) specifies the space attribute for the text output primitive, 
in world coordinates. It is used to insert additional space between characters in 
text strings. If the charprecision attribute is set to STRING, 
set_char space ( ) has no effect. 

Set Character Up Vector 2 set_charup_2 (dx, dy) 

float dx, dy; 

set_charup_2 ( ) specifies the champ attribute for the text output primitive, 
in world coordinates. Note that the dz offset is set to 0.0 for this fimctioa If the 
charprecision attribute is set to STRING, set_charup_2 ( ) has no effect; oth- 
erwise it specifies the upward direction for the characters. This provides for 
slanting, mirror imaging, and so on, for characters. 

Set Character Up Vector 3 set_charup_3 (dx, dy, dz) 

float dx, dy, dz; 

set_charup_3 ( ) specifies the charup attribute for the text output primitive, 
in world coordinates. If the charprecision attribute is set to STRING, 
set_charup_3 ( ) has no effect; otherwise it specifies the direction of upward 
for the characters. This provides for slanting, mirror imaging and such, for char- 
acters. 

Set Character Path 2 set_charpath_2 (dx, dy) 

float dx, dy; 

set_charpath_2 ( ) specifies the charpath attribute for the text output 
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primitive, in world coordinates. Note that the dz offset is set to 0.0 for this func- 
tion. If the charprecision attribute is set to STRING, set_charpath_2 ( ) has 
no effect; otherwise the character string is written in this direction. 

Set Character Path 3 set_charpath_3 (dx, dy, dz) 

float dx, dy, dz; 

set_charpath_3 ( ) specifies the charpath attribute for the text output primi- 
tive, in world coordinates. If the charprecision attribute is set to STRING, 
set_charpath_3 ( ) has no effect; otherwise the character string is written in 
this direction. 



Specify Text Justification (No set char just ( just) 

Effect) int just; 

set_char just ( ) specifies how text strings should be justified. This function 
has no effect in the current release of SunCore. 



Set Character Precision set_charprecision (charprecision) 

int charprecision; /* STRING, CHARACTER */ 

set_charprecision ( ) selects the method of drawing text. 

STRING Specifies characters of fixed size and orientation, which are 

drawn rapidly using raster operations. This is the default. 

CHARACTER Specifies Hershey vector fonts, which can be clipped and 
transformed. 

Set Marker Symbol set_marker_symbol (marker) 

int marker; /* Character to use as Marker - 32 . . 127 */ 

set_marker_symbol ( ) establishes the marker symbol primitive attribute. 
The character specified by the marker argument in the 
set_marker_symbol ( ) function call is subsequently used as the marker 
character by the marker and polymarker functions. 



Set Pick ID set_pick_id (pick_id) 

int pick_id; 

set_pick_id ( ) specifies the pick id attribute for output primitives. The pick 
id attribute is only used by the await _pick input function. Subsequent output 
primitives are identified by the specified pick id when they are detected by the 
mouse pointing device, via the await_pick ( ) input function. 

Select Rasterop to Display set ras terop ( rop) 

Memory (SunCore Extension) rop; /* xorrop, orrop, normal */ 

set_r aster op ( ) selects Xor’ing or or’ing of primitives to display memory. 
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Specify All Primitive set_primitive_attributes (attributes) 

Attributes struct { 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} *attributes; 

set_primitive_attributes ( ) is a composite function which provides a 
means to set all the primitive attributes in a single function call. Note that the 
function call: 

set_primitive_at tributes (&PRIMATTS) 

sets all the primitive attributes to their default values. PRIMATTS is defined in 
<usercore . h>, 

6.3. Inquiring Primitive The functions described in the sections that follow allow the user to inquire static 

Static Attribute Values attribute values of the SunCore primitives. 

□ A 2D inquiry function was used when a 3D inquiry function should have been 
used to avoid loss of information. 

Inquire Color Indices inquire_color_indices (surface_name, il, 12, 

red_array, green_array, blue_array) 
struct vwsurf *surface_name; /* See appendix B */ 
int il, i2; /* Start and end table indices */ 

float red_array[]; /* Range is 0.0 thru 1.0 */ 
float green_array [] ; /* Range is 0.0 thru 1.0 */ 

float blue_array [ ] ; /* Range is 0.0 thru 1.0 */ 

inquire_color_indices ( ) obtains die color lookup table for the specified 
view surface, surface _name is the name of the view surface for which the color 
lookup tables should be obtained. 

inquire_color_indices ( ) takes entries from the color lookup tables, 
starting at index il (relative to zero) and ending at index i2. The color lookup 
tables for a given color are stored in 

array [0] through array [i2-il] 

Inquire Line Index inquire line index (index) 

int * index; 

inquire_line_index ( ) obtains the current color index for coloring line 
and polyline output primitives. 
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Inquire Fill Index 



Inquire Text Index 



Inquire Linewidth 



Inquire Linestyle 



Obtain Polygon Shading 
Method 



Inquire Polygon Edge Style 



Inquire Pen 



Inquire Font 



Inquire Character Size 



inquire_fill_index (index) 
int *index; 

inquire_f ill_index ( ) obtains the current color index for coloring 
polygon and raster output primitives. 

inquire_text_index ( index) 
int * index; 

inquire_text_index ( ) obtains the current color index for coloring marker 
and text output primitives. 

inquire_linewidth (linewidth) 
float *linewidth; 

inquire_linewidth ( ) obtains the linewidth attribute, in percent of NDC 
space, for the output primitives. 

inquire_linestyle (linestyle) 

int *linestyle; /* SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 

inquire_linestyle ( ) obtains the linestyle attribute for the output primi- 
tives. 

inquire_polygon_interior_style (style) 
int * style; /* PLAIN, SHADED */ 

inquire_polygon_inter ior_style ( ) obtains the method of filling for 
polygons. 

inquire_jpolygon_edge_style (style) 
int *style; /* SOLID, INTERIOR */ 

inquire_polygon_edge_style ( ) obtains the current method of drawing 
polygon edges. 

inquire_pen (pen) 

int *pen; /* Device dependent pen selector */ 
inquire_pen ( ) obtains the pen attribute for the text output primitive. 

inquire_font (font) 

int *font; /* ROMAN, GREEK, SCRIPT, OLDENGLISH, */ 

/* STICK, SYMBOLS */ 

inquire_f ont ( ) obtains the font attribute for the text output primitive. 

inquire_charsize (charwidth, charheight) 
float *charwidth, *charheight; 

inquire_charsize ( ) obtains the charsize attribute for the text output prim- 
itive. 
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Inquire Character Spacing 



Inquire Character Up 
Vector 2 



inquire_char space (charspace) 
float *charspace; 

inquire_char space ( ) obtains the charspace attribute for the text output 
primitive. 

inquire_charup_2 (dx, dy) 
float *dx, *dy; 

inquire_charup_2 ( ) obtains the charup attribute for the text output primi- 
tive. 



Inquire Character Up inquire_charup_3 (dx, dy, dz) 

Vectors float *dx, *dy, *dz; 

inquir e_charup_3 { ) obtains the charup attribute for the text output primi- 
tive. 



Inquire Character Path 2 inquire_charpath_2 (dx, dy) 

float *dx, *dy; 

inquire_charpath_2 ( ) obtains the charpath attribute for the text output 
primitive. 

Inquire Character Path 3 inquire_charpath_3 (dx, dy, dz) 

float *dx, *dy, *dz; 

inquire_charpath_3 ( ) obtains the charpath attribute for the text output 
primitive. 



Obtain Justification Attribute inquirechar just (just) 

int *just; 

inquir e_char just () obtains the justification attribute for text strings. 



Obtain Current Rasterop inquire rasterop ( rop) 

(SunCore Extension) int *rop; /* xorrop, orrop, normal */ 

inquire_rasterop ( ) determines the current setting of the rasterop attri- 
bute. 



Inquire Character Precision inquire_charprecision (charprecision) 

int *charprecision; /* STRING, CHARACTER */ 

inquire_charprecision ( ) obtains the charprecision attribute for the text 
output primitive. 



Inquire Pick ID 



inquire_pick_id (pick_id) 
int *pick_id; 



inquire_pick_id ( ) obtains the pick id attribute for output primitives. 
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Inquire Marker Symbol 



Obtain All Primitive 
Attributes 



6.4. Retained Segment 
Static Attributes 



Set Image Transformation 
Type 



inquire_marker_symbol (symbol) 
int *symbol; /* 32 . . 127 */ 

inquire_marker_symbol ( ) obtains the current value of the marker sym- 
bol. 



inquirejprimitive_attributes (attributes) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float 1 inwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} *attributes; 

inquire_j>rimitive_attributes ( ) is a composite function which pro- 
vides a means to obtain all the primitive attributes in a single function call. 



There is only one static attribute for segments. This is the image transformation 

type attribute. This attribute can take on one of five values: 

NONE Retained segment on which no translation, scaling, or rotation can be 
performed. 

XLATE2 Translatable retained segment. The segment can be moved 
(translated) in 2D (r and y of NDC space). 

XFORM2 Fully transformable retained segment. The segment can be moved 
(translated), rotated, and scaled (have its size changed) in 2D (x and 
y of NDC space). 

XLATE3 Translatable retained segment. The segment can be moved 
(translated) in 3D (x and y of NDC space). 

XFORM3 Fully transformable retained segment The segment can be moved 
(translated), rotated, and scaled (have its size changed) in 3D (x, y 
and z of NDC space). 



The image tran^ormation type attribute is set when a segment is created and can- 
not be changed at any time during the life of the segment. The default value of 
image transformation type is NONE. 

The functions described below are used to set and inquire about the values of 
image transformation type. 



set_image_transformation_type (type) 

int type; /* NONE, XLATE2, XF0RM2, XLATE3, XF0RM3 */ 
s et_image_trans format ion_type ( ) specifies the image 
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Inquire Image 
Transformation Type 



Inquire Segment Image 
Transformation Type 



6.5. Setting Retained 
Segment Dynamic 
Attributes 



transformation type attribute for subsequently created segments. 

inquire_image_trans format ion_type (type) 

int *type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

inquire_image_transf ormation_type ( ) obtains the current value of 
the image tranrformation type attribute. 

inquire_segment_image_transformation_type (segment_name, type) 
int segment_name; /* Name of segment for inquiry */ 
int *type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

inquire_segment_image_transf ormation_type {) obtains the 
image transformation type for a specified segment. 

In addition to the one static attribute described above, there are a number of 
dynamic attributes which apply to segments. Each retained segment has its own 
set of dynamic attributes, as listed below. 

Visibility 

indicates whether the segment should have a visible image. There are only 
two values of this attribute, namely: TRUE and FALSE. 

SunCore sets visibility to TRUE at initialization time. 

Highlighting 

indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by briefly blinking the segment. There are only two 
values of the highlighting attribute, namely, TRUE and FALSE. 

SunCore sets highlighted to FALSE at initialization time. 

Detectability 

indicates whether the retained segment can be detected by the 
await_pick ( ) input primitive. A value of 0 means that the segment is 
not pickable. If two segments overlap, the one with the greatest value of 
detectability is the one that gets picked. SunCore sets detectability to the 
default value of 0 at initialization time. 

Image Transformation 

indicates how the image of a retained segment is scaled, rotated, or 
translated. Image transformations are done in NDC space, that is, after all 
viewing operations have been performed. Image transformations do not 
compose and do not cumulate. Whenever any function affecting a segment’s 
image transformation is called, the transformation is reset to reflect only the 
values specified by the call. The image transformation attribute of a seg- 
ment must be consistent with its image transformation type attribute (for 
instance, if the image transformation type is XLATE2, it is an error to 
attempt to rotate the segment). 

SunCore sets the default image transformation to the identity transformation 
(that is, no translation, scaling, or rotation) at initialization. 
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Set Visibility 



Set Highlighting 



Set Detectability 



Set Image Translate 2 



There are two classes of functions for setting retained segment dynamic attri- 
butes. One class sets the default attributes for subsequently created segments; the 
other sets attributes on a named segment basis. 

□ There is no retained segment called segment name. 

□ One or more of the attributes is incorrect. 

□ The segment’s image transformation type attribute value is incompatible with 
the requested function. 

set_visibility (visibility) 

int visibility; /* TRUE or FALSE */ 

set_visibility ( ) specifies the default visibility attribute for subsequently 
created segments. This does not affect the visibility of existing segments or the 
currently open segment. 

set_highlighting (highlighting) 

int highlighting; /* TRUE or FALSE */ 

set_high lighting ( ) specifies the default highlighting attribute for subse- 
quently created segments. 

set_detect ability (detectability) 

int detectability; /* 0 thru 2 to the 31rd power */ 

set_detectability ( ) specifies the default detectability attribute for subse- 
quently created segments. 

set_image_translate_2 (tx, ty) 

float tx, ty; /* x and y translation values in NDC */ 

set_image_translate_2 ( ) sets the default image transformation attribute 
for subsequently created segments. The default image transformation is set to a 
2D translate by tx and ty. 



Set Image Transformation 2 set_image_transfonnation_2 (sx, sy, a, tx, ty) 

float sx, sy; /* x and y scale factors */ 
float a; /* rotation value in radians 
counter-clockwise about z axis */ 
float tx, ty; /* x and y translation values in NDC */ 

set_image_transf ormation_2 ( ) sets the default image transformation 
for subsequently created segments. The default transformation is set to a 2D 
scale by sx and sy, rotation by a, and translation by tx and ty. The order of 
transformation is: 

1. Scale about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rota- 
tion of nil radians will rotate the x axis into the y axis. 

3. Translate. 
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To scale and rotate about a point x, y, add dxvotx and add dy to ty, where 
dx=x -(x*sx*cos (a )-y*sy*sin (a )) 



dx=y -(x*‘sx*sin (a )+y*sy*cos (a )) 



Set Image Translate 3 set_image_translate_3 (tx, ty, tz) 

float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 

set_image_translate_3 ( ) sets the default image transformation attri- 
bute, in NDC space, for subsequently created segments. The default image 
transformation is set to a 3D translate by tc, ty and tz. 

Set Image Transformation 3 set_image_transfonnation_3 (sx, sy, sz, ax, ay, az, tx, ty, tz] 

float sx, sy, sz; /* x, y, and z Scale Factors */ 
float ax, ay, az; /* Rotation Values in radians clockwise */ 
/* about the x, y, and z axes */ 
float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 

set_image_transf ormation_3 ( ) sets the default image transformation 
attribute for subsequentiy created segments. The default image transformation is 
set to a 3D scale by sx, sy, sz, a 3D rotation by ax ay, az, and a 3D translation by 
tx, ty, tz. The order of transformation is: 

1. Scale about (0.0, 0.0, 0.0) in NDC space, 

2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the r-axis, then about 
the y-axis, and then about the z-axis. Since NDC space is a left-handed coor- 
dinate system, rotations are computed using the left-hand rule. When the ori- 
gin is viewed from the positive side of the axis of rotation, clockwise rota- 
tions correspond to positive rotations. 

3. Translate. 



Set Segment Visibility set_segment_visibility (segment_name, visibility) 

int segment_name; 

int visibility; /* TRUE or FALSE */ 

set_segment_visibility ( ) specifies the visibility attribute for the 
named segment. When visibility is set to FALSE, the segment is erased from the 
view surfaces. The segment is redrawn again when visibility is set to TRUE. 

Set Segment Highlighting set_segment_highlighting(segment_name, highlighting) 

int segment_name; 

int highlighting; /* TRUE or FALSE */ 

set_segment_highlighting ( ) specifies the highlighting attribute for the 
named segment. When highlighting is set to TRUE, the segment is blinked once. 
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Set Segment Detectability 



Set Segment Image 
Translate 2 



Set Segment Image 
Transformation 2 



set_segment_detect ability (segment_name, detectability) 
int segment_name ; 

int detectability; /* 0 thru 2 to the 31rd power */ 

set_segment_detect ability ( ) specifies the detectability attribute for 
the named segment. When detectability is set to 0, the segment cannot be picked 
by the await_pick ( ) input function. If two segments overlap, the segment 
with the greatest detectability is picked. 

set_segment_image_translate_2 (segment_name/ tx, ty) 
int segment_name; 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

set_segment_image_translate_2 ( ) sets the image transformation 
attribute for the named segment. The image transformation is set to a 2D 
translate by tx, ty. The named segment is erased from the view surface and then 
redrawn after the new image transformation is applied. This may be done while 
the segment is open. 

set_segment_image_transf ormation_2 ( segment_name, 
sx, sy, a.f tx, ty) 
int segment_name; 
float sx; /* X Scale Factor */ 

float sy; /* y Scale Factor */ 

float a; /* Rotation Value in radians 
clockwise about z axis */ 
float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

set_segment_image_transf ormation_2 ( ) sets the image transforma- 
tion attribute for the named segment The image transformation is set to a 2D 
scale by sx and sy, a 2D rotation by a, and a 2D translation by tx and ty. The 
order of transformation is: 

1 . Scale about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rotation 
of 7 c/ 2 radians will rotate the x axis into the y axis. 

3. Translate. 

To scale and rotate about a point x, y, add dx\o tx and add dy to ty, where 
dx=x-{x*sx* cos(a y-y*sy* sin(a )) 



dx=y-{x*sx* sin(a )+y*sy* cos(a )) 

The named segment is erased from the view surface and then redrawn after the 
new image transformation is applied. This may be done while the segment is 
open. 
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Set Segment Image 
Translate 3 



Set Segment Image 
Transformation 3 



6.6. Inquiring Retained 
Segment Dynamic 
Attributes 



set_segment_image_translate_3 (segment_name, tx, ty, tz) 
int segment_name; 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

set_segment_image_translate_3 ( ) sets the image transformation 
attribute for the named segment. The image transformation is set to a 3D 
translate by tx, ty, tz. The named segment is erased from the view surface and 
then redrawn after the new image transformation is applied. This may be done 
while the segment is open. 

set_segment_image_t rans format ion_3 ( segment_name , 
sx, sy, sz, ax, ay, az, tx, ty, tz) 
int segment_name; 
float sx; /* x Scale Factor */ 

float sy; /* y Scale Factor */ 

float sz; /* z Scale Factor */ 

float ax; /* Rotation Value in radians clockwise 
about the x axis */ 

float ay; /* Rotation Value in radians clockwise 
about the y axis */ 

float az; /* Rotation Value in radians clockwise 
about the z axis */ 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

set_segment_image_transf ormation_3 ( ) sets the image transforma- 

tion attribute for the named segment. The image transformation is set to a 3D 
scale by sx, sy, sz, a 3D rotation by ax, ay, az, and a 3D translation by tx, ty, tz. 
The order of transformation is: 

1 . Scale about (0.0, 0.0, 0.0) in NDC space. 

2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the x-axis, then about 
the y-axis, and then about the z-axis. Since NDC space is a left-handed coor- 
dinate system, rotations are computed using the left-hand rule. When the ori- 
gin is viewed from the positive side of the axis of rotation, clockwise rota- 
tions correspond to positive rotations. 

3. Translate. 

The named segment is erased from the view surface and then redrawn after the 
new image transformation is applied. This may be done while the segment is 
open. 

The functions described below are for inquiring the settings of the dynamic attri- 
butes for retained segments. There are two classes of functions for inquiring 
retained segment dynamic attributes. One class obtains the default attributes for 
subsequently created segments and the other obtains attributes on a named seg- 
ment basis. 
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Inquire Visibility 



Inquire Highlighting 



Inquire Detectability 



Inquire Image Translate 2 



Inquire Image 
Transformation 2 



Inquire Image Translate 3 



□ There is no segment called segment name. 

o The default image transformation attribute value is of a more complex type 
than the inquiry function used. 

□ The segment’s image transformation type attribute value is incompatible with 
the requested function. 

□ The segment’s image transformation type attribute value is of a more complex 
type than the inquiry function used. 

inquire_visibility (visibility) 

int * visibility; /* TRUE or FALSE */ 

inquire_visibility ( ) obtains the default visibility attribute for subse- 
quently created segments. 

inquire_high lighting (highlighting) 
int *highlighting; /* TRUE or FALSE */ 

inquire_highlighting ( ) obtains the default highlighting attribute for the 
subsequently created segments. 

inquire_detect ability (detectability) 

int *detectability; /* 0 thru 2 to the 31rd power */ 

inquire_detectability ( ) obtains the default detectability attribute for 
the subsequently created segments. 

inquire_image_translate_2 (tx, ty) 

float *tx, *ty; /* x and y Translation Values in NDC */ 

inquire_image_translate_2 ( ) obtains the 2D translation components 
of the default image transformation for subsequently created segments. 

inquire_image_transfonnation_2 (sx, sy, a, tx, ty) 
float *sx, *sy; /* x and y Scale Factors */ 
float *a; /* Rotation Value in radians 
clockwise about the z axis */ 
float *tx, *ty; /* x and y Translation Values in NDC */ 

inquire_image_transf ormation_2 ( ) obtains the 2D scale factor, rota- 
tion, and translation components of the default image transformation attribute for 
subsequently created segments. 

inquire_image_translate_3 (tx, ty, tz) 

float *tx, *ty, *tz; /* x, y, and z Translation Values in NDC 

inquire_image_translate_3 ( ) obtains the 2D translation components 
of the default image transformation attribute for subsequently created segments. 
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Inquire Image 
Transformation 3 



Inquire Segment Visibility 



inquire_iraage_transfonnation_3 (sx, sy, sz, ax, ay, az, tx, ty< 
float *sx, *sy, *sz; /* x, y, and z Scale Factors */ 

float *ax, *ay, *az; /* Rotation Values in radians clockwis 

about the x, y, and z axes */ 

float *tx, *ty, *tz; /* x, y, and z Translation Values in 1 

inquire_image_transf ormation_3 ( ) obtains the 3D scale factor, rota- 
tion, and translation components of the default image transformation attribute for 
subsequently created segments. 

inquire_segment_visibility ( segment_name , visibility) 
int segment_name; 

int *visibility; /* TRUE or FALSE */ 

inquire_segment_visibility ( ) obtains the visibility attribute for the 
named segment. 



Inquire Segment Highlighting inquire_segment_highlighting(segment_name, highlighting) 

int s egment_name ; 

int *highlighting; /* TRUE or FALSE */ 

inquire_segment_highlighting ( ) obtains the highlighting attribute 
for the named segment. 



Inquire Segment Detectability inquire_segment_detectability (segment_name, detectability) 

int segment_name; 

int *detectability; /* 0 thru 2 to the 31rd power */ 

inquire_segment_detectability ( ) obtains the detectability attribute 
for the named segment. 



Inquire Segment Image 
Translate 2 



Inquire Segment Image 
Transformation 2 



inquire_segment_iniage_translate_2 (segTnent_name, tx, ty) 
int segment_name; 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC */ 

inquire_segment_image_translate_2 ( ) obtains the 2D translation 
components of the named segment’s image transformation attribute. 

inquire_segment_iinage_transf ormation_2 ( segment_name , 
sx, sy, a, tx, ty) 
int segment_name; 
float *sx; /* X Scale Factor */ 

float *sy; /* y Scale Factor */ 

float *a; /* Rotation Value in radians clockwise 

about the z axis */ 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC */ 

inquire_segment_image_transf ormation_2 () obtains the 2D scale 
factor, rotation, and translation components of the named segment’s image 
transformation attribute. 




Revision A, of 9 May 1988 




Ch^ter 6 — Attributes 93 



Inquire Segment Image 
Translate 3 



Inquire Segment Image 
Transformation 3 



inquire_segment_image_translate_3 (segment_name, tx, ty, tz) 
int segment_name; 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC */ 

float *tz; /* z Translation Value in NDC */ 

inquire_segment_image_translate_3 ( ) obtains the 3D translation 
components of the named segment’s image transformation attribute. 

inquire_segment_image_transf ormation_3 (segment_name, 
sx, sy, sz, ax, ay, az, tx, ty, tz) 
int segment_name; 
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inquire_segment_image_transf ormation_3 ( ) obtains the 3D scale 
factor, rotation, and translation components of the named segment’s image 
transformation attribute. 
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Input Primitives 



SunCore supports several logical input devices providing for interactive use of 
the graphics system. The physical input devices provided are the keyboard and 
the mouse. The mouse is versatile in that it can be used both as a pointer and a 
button device. 

In the terminology of the ACM Core specification, input devices fall into two dis- 
tinct classes, namely: devices that generate events, and devices that may only be 
sampled for position or numerical values. SunCore supports the ACM Core stan- 
dard level 2 input (synchronous); hence no event generation or event queue is 
supported. The supported logical devices in SunCore are: 

T able 7-1 Input Devices Supported By SunCore 



Device 


Descruption 


PICK 


identifies a segment or a primitive within a seg- 
ment. SunCore uses the mouse as a PICK dev- 


KEYBOARD 


ice. 

provides alphanumeric information to the appli- 
cation program. 


BUTTON 


provides a means of choosing among several 
alternatives. In SunCore, the three BUTTON 
devices are on the mouse. 


STROKE 


generates a sequence of positions in NDC space. 
In SunCore, the STROKE device is the mouse. 


LOCATOR 


provides a position in NDC space. SunCore uses 
the mouse as the LOCATOR device. 


VALUATOR 


provides a scalar value to the application pro- 
gram which samples it. SunCore uses the mouse 
as the valuator device. 



A logical input device must be initialized before it can be used. 



7.1. Initializing and The functions described in the sections that follow are used to initialize and ter- 

Terminating Input minate input devices. These functions are normally called at the beginning and 

Devices end of a SunCore application program. 
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Initialize a Specific Device initialize_device (device_class, device_number) 

int device_class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

initialize_device ( ) initializes a specific logical device. This function 
must be called before accessing any of the input devices. An initialized input 
device which uses position information from the mouse must be associated with 
an initialized view surface (as an echo surface) before valid data can be read from 
the device. See Appendix B for details. 

Note: that if the KEYBOARD device is initialized and the program crashes before 
the KEYBOARD device is terminated, the tty will not echo and cbreak will be set. 
To recover from this condition, type ‘reset’ followed by a carriage return. 

□ The device specified by device number is not initialized. 

□ The device specified by device number is already initialized. 

Disable a Specific Device terminate_device (device_class, device_nmnber) 

int device_class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_niamber; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

terminate_device ( ) disables a specific device. 

□ The device specified by device_number is not enabled. 

7.2. Device Echoing Device echoing means that SunCore can provide a visible indication to the user 

that the system has seen the input from a specific input device. 

SunCore provides the means whereby the application programmer can control 
the way in which input devices are echoed to the user of the graphics system. 

Firstly, the types of echoing for each device are defined here. The tables below 
describe the types of echoing for specific devices. 
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Table 7-2 



Table 7-3 



Table 7-4 



Table 7-5 



Echoing for PICK Device 



Echo Type 


Actions Performed 


0 


No echo 


1 


SunCore blinks the picked segment briefly. A 
printer’s fist (pointing finger) indicates the 
position of the PICK device. 


2 


A printer’s fist (pointing finger) indicates the 
position of the PICK device. SunCore does 
not blink the picked segment 


Echoing for KEYBOARD Device 


Echo Type 


Actions Performed 


0 


No echo 


1 


The string which the user typed on the KEY- 
BOARD device is echoed on the screen start- 
ing at the echo reference position. 


Echoing for BUTTON Device 


Echo Type 


Actions Performed 


0 


No echo 


1 


No echo 


Echoing for STROKE Device 


Echo Type 


Actions Performed 


0 


No echo 


1 


a printers fist (pointing finger) sign is 
displayed at the cursor position. 


2 


A string of dots is drawn to follow the path of 
the cursor, (not implemented) 


3 


A solid line is drawn to follow the path of the 
cursor, (not implemented) 


4 


a printers fist sign is displayed at the final 
position of the cursor, (not implemented) 
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Table 7-6 Echoing for LOCATOR Device 



Echo Type 


Actions Performed 


0 


No echo 


1 


A printers fist (pointing finger) sign is 
displayed at the position of the LOCATOR 
device. 


2 


A solid line is drawn connecting the echo 
reference point with the LOCATOR. 


3 


A solid line is drawn connecting the echo 
reference point with the x coordinate of the 
LOCATOR. 


4 


A solid line is drawn connecting the echo 
reference point with the y coordinate of the 
LOCATOR. 


5 


A solid line is drawn connecting the echo 
reference point with either the x coordinate, or 
the y coordinate, of the LOCATOR, which- 
ever is farthest from the echo reference point 


6 


A box is drawn with the position of the 
LOCATOR as one comer, and the echo refer- 
ence point as the opposite comer. 



Table 7-7 Echoing for VALUATOR Device 



Echo Type 


Actions Performed 


0 


No echo 


1 


The current value of the valuator is displayed 
on the screen starting at the echo reference 
point. 


2-11 


SunCore does not perform the actions as 
described in the ACM Core specification, 
which sets the values of the valuator into vari- 
ous parameters of the 
image jransfommtionjype attribute of 
retained segments. SunCore leaves this up to 
the application program. 



set_echo (device_class, device_number, echo_type) 
int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 
int echo_type; 

set_echo ( ) determines the echo type for a input device. 
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set_echo_group (device_class, device_number_array, n, echo_type) 
int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_ninnber_array [] ; 
int n; /* niimber of devices in array */ 
int echo_type; 

set_echo_group ( ) determines the echo type for an input device class. 

Define Echo Reference Point set_echo_position(device_class, device_number, echo_x, echo_y) 

int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_ninnber; 

float echo_x; /* x Coordinate of Echo Point */ 

float echo_y; /* y Coordinate of Echo Point */ 

set_echo_position ( ) specifies the position, in NDC space, which will be 
used as the echo reference point. The coordinates must lie within the bounds of 
NDC space, or set_echo_position ( ) will set the echo reference point to be 
the point in NDC space closest to the specified point. The echo reference point 
that this function defines is used for certain types of echo such as rubber band 
LCXTATOR echo. 

Define View Surface for Echo set_echo_surface (device_class, device_number, surf ace_name) 

int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_number; 

struct vwsurf *surface_name; /* See Appendix B */ 

set_echo_surf ace ( ) specifies the viewing surface on which echoing will 
be done. An initialized input device which uses position information from the 
mouse must be associated with an initialized view surface (as an echo surface) 
before valid data can be read from the device. See Appendix B for details. If a 
NULL pointer is given for the surface name argument, any association of the 
specified input device with an echo surface is ended. 

7.3. Setting Input Device The functions described in the sections that follow are used to define certain 

Parameters parameters for each of the logical input devices. These functions are normally 

called at the beginning of a SunCore application program. 

Initialize LOCATOR Position set_locator_2 (locator_number, x, y) 

int locator_number; 
float x; 
float y; 

set_locator_2 ( ) sets the initial LOCATOR position in NDC space. 
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set_valuator (valuator_number, initial_value, low, high) 
int valuator_number; 
float initial_value; 
float low; 
float high; 

set_valuator ( ) sets ihe value and range for the valuator device. The 
default values are: initial_value=0.0, lcfw==0.0, and high=1.0. 

s e t_ke ybo ard(keyboa r d_numbe r , bu f f e r_s i z e , 
initial_string, initial_cursor_position) 
int keyboard_nmnber; 
int buffer_size; 
char *initial_string; 
int initial_cursor_position; 

set_keyboard ( ) sets the size of the character buffer for the KEYBOARD 
device, the initial character string, and the initial character cursor counting from 
the echo reference position. SunCore uses default values of buffer _size=%0, 
initial_string=" enter” , and initial cursor _position=l. The maximum 
buffer size and the maximum length of initial string are 80 characters. 

Initialize STROKE Device set_stroke (stroke_number, buffer_size, distance, time) 

int stroke_number; /* Device Number */ 
int buffer_size; /* not used */ 

float distance; /* Minimum distance to move */ 

int time; /* not used */ 

set_stroke ( ) sets parameters for the STROKE device. The buffer size 
argument is the maximum number of x, y points in a STROKE. The distance 
argument is the minimum distance, in NDC space, which the mouse must move 
before a new point is added to the x, y list comprising the STROKE. The default 
setting is distance =0.01, 

Initialize PICK Device set_pick (pick-number, aperture) 

int pick-number; /* device number */ 
float aperture; /* device aperture */ 

set pick ( ) sets the aperture for the PICK device. The aperture argument 
provides control over the ‘sensitivity’ of the PICK device. A square is defined 
with its center at the cursor position and with sides of length 2 * aperture. Seg- 
ments that intersect this square can be picked, aperture is given in NDC space. 
An error is returned if the pick-number is incorrect or if the aperture ^.0. The 
default aperture square has two pixels per side. 

7.4. Reading From Input SunCore has several functions for interrogating input devices. These function 
Devices allow the application programmer a great deal of flexibility in user-interface 

design. 
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Wait for BUTTON Device 



Wait for PICK Device 



await_any_button (time, button_nuiiiber) 

int time; /* Time in microseconds to wait */ 

int *button_number; /* BUTTON which was hit */ 

await_any_button ( ) waits for the user to click any of the BUTTON dev- 
ices. await_any_button ( ) waits for the user to click any BUTTON device, 
or until the time specified by the time parameter expires. If the time argument is 
exactly zero, the BUTTON devices are checked once, then the function returns to 
the caller immediately. 

If a BUTTON device is clicked before time expires, the number of the BUTTON 
device is returned in the button number parameter. If the user does not click any 
BUTTON device before time expires, the function returns a BUTTON device 
number of zero. 

For the mouse, BUTTON device numbers 1, 2, and 3 represent the left, middle, 
and right buttons, respectively, when the buttons are facing away from the user. 

await_pick (time, pick_number, segment_name, pick_id) 
int time; /* Time in microseconds to wait */ 
int pick_number; 
int * segment_name ; 
int *pick_id; 

await_pick ( ) waits for the user to pick an output primitive within a visible 
and detectable retained segment. await_pick ( ) waits for the user to click the 
left hand button on the mouse, or until the time specified by the time parameter 
expires. If the time argument is exactly zero, the function tests the button once, 
and if the button has been clicked, performs the pick operation. 

If the button is clicked before time expires, the function returns the 
segment ncune of the segment that the PICK device is pointing at, and the 
pick id parameter is set to the value of the pick id attribute of the primitive that 
was picked. If the user does not click any mouse button before time expires, or 
no segment is found where the user points, the function sets the segment name 
and pick id parameters to zero. 

await_pick ( ) only searches those segments which are visible and detectable 
and appear on the echo surface of the specified PICK device. Primitives within a 
segment have bounded volume descriptors. The square pick aperture must inter- 
sect one of these ‘extents’ in order that the segmentjiame and pick id be 
remmed. If more than one segment is at the point, the segment with the highest 
value of the detectability attribute is returned. Detectability may be set to zero to 
prevent a segment from being picked. 

□ The specified PICK device does not exist. 
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Wait for Input from the 
KEYBOARD 



Wait for User to Draw a 
Curve 



await_keyboard (time, keyboard_number, input_string, length) 

int time; /* Time in microseconds to wait */ 

int keyboard_number; 

char *input_string; 

int * length; 

await_keyboard ( ) waits for the user to type a line of input on the KEY- 
BOARD device. await_keyboard ( ) waits for die user to enter data at the 
KEYBOARD device, or until the time specified by the time parameter expires. If 
the time argument is exactly zero, the function tests once to see if a character has 
been typed, and then returns to the caller. 

If any data is entered at the KEYBOARD device before time expires, the function 
returns the typed characters in an array pointed to by input string. The length of 
this character string is returned in length. The string is null terminated. If the 
user does not enter any data before time expires, the function sets the length 
parameter to zero. If a carriage-return or newline character is typed, the function 
returns with the input string containing a newline character as the last non-null 
character. 

□ The specified KEYBOARD device does not exist. 

await_stroke_2 (time, stroke_number, array_size, 
x_array, y_array, number_points) 
int time; /* Time in microseconds to wait */ 
int stroke_number ; /* STROKE device to wait for */ 

int array_size; /* Maximum size of x and y arrays */ 
float x_array[]; 
float y_array[]; 

int *number__points; /* Number of x, y coordinates 
actually read */ 

await_stroke_2 ( ) waits for the user to draw a curve, consisting of a list of 
points in NDC space, using the mouse. A curve in this context means a string of 
line segments. await_stroke_2 ( ) waits for the user to draw a curve using 
the mouse, or until the time specified by the time parameter expires. If the time 
argument is exactly zero, the function tests once to see if a curve has been drawn, 
and then returns to the caller. 

The curve starts at the current position of the LOCATOR, and finishes when the 
user clicks button 3 on the mouse. When the function returns, the number of x, y 
coordinates actually read is returned in the number _points argument. When the 
number of points read equals array size the function returns before time expires. 
Note: The BUTTON device must be initialized for await_stroke_2 ( ) to 
work. 
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await_any_button_get_locator_2 (time, locator_number, 
button_number, x, y) 

int time; /* Time in microseconds to wait */ 
int locator_number; /* LOCATOR device to wait for */ 
int *button_number; /* BUTTON which was clicked */ 
float *x, *y; /* Returned point in NDC */ 

await_any_button_get_locator_2 ( ) waits for the user to click any of 
the mouse buttons. When the button is clicked, the function returns the current 
NDC coordinates of the LOCATOR. 

await_any_button_get_locator_2 ( ) waits for the user to click any 
mouse button, or until the time specified by the time argument expires. If the 
time argument is exactly zero, the function checks if any buttons have been 
clicked immediately and then returns. 

If the time expires before the user has clicked any of the mouse buttons, the func- 
tion returns a zero in the button number argument. 

await_any_button_get_valuator (time, valuator_number, 
button_number, value) 

int time; /* Time in microseconds to wait */ 
int valuator_number; /* VALUATOR number to read from */ 
int *button_number; /* BUTTON which was clicked */ 
float *value; /* Value of valuator */ 

await_any_button_get_valuator ( ) waits for the user to click any of 
the mouse buttons, or for a specified time. When the button is clicked, the func- 
tion returns the current value of the valuator. 

await_any_button_get_valuator ( ) waits for the user to click any 
mouse button, or until the time specified by the time argument expires. If the 
time argument is exactiy zero, the function checks if any buttons have been 
clicked and then returns immediately. 

If the user clicks one of the mouse buttons, the function returns with the value of 
the valuator, and the number of the button which was clicked. If the time expires 
before the user has clicked any of the mouse buttons, the function returns a zero 
in the button_number argument. Movement of the mouse left or right lowers or 
raises the value of the valuator. Note: The BUTTON device must be initialized 
for await_any_button_get_valuator ( ) to work. 

get_mouse_state (device_class, device_number, x, y, buttons) 
int device_class; /* PICK, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_number; 
float *x, *y; 
int *buttons; 

get_mouse_state ( ) reads the low level mouse x, y and button information 
corresponding to a particular input device. The buttons are up-down encoded, 
and the location of the mouse is in NDC space. 



Low Level Mouse Support 
(SunCore extension) 



Read VALUATOR When 
BUTTON Clicked 



Read LOCATOR When 
BUTTON Clicked 
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Bit 0 of buttons is the right-hand mouse button. 

Bit 1 of buttons is the middle mouse button. 

Bit 2 of buttons is die left-hand mouse button. 

A zero bit means that the button is up, while a one bit means that the button is 
down. 

7.5. Inquiring Input Status The functions described in the sections that follow are used to inquire various 
Parameters parameters of the logical input devices. 

Obtain Type of Echo for inc[uire_echo (device_class, device_number, echo_type) 

Device int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int de vice_n umber; 
int *echo_type; 

inquire_echo ( ) obtains the echo type for the specified device. 

Obtain Echo Reference Point inquire_echo_position (device_class, device_number, 

echo_x, echo^y) 
int device_class; 
int device_number; 

float *echo_x; /* x Coordinate of Echo Point */ 

float *echo_y; /* y Coordinate of Echo Point */ 

inquire_echo_position ( ) obtains the position, in NDC space, of the 
echo reference point for the specified device. 

Obtain View Surface for Echo inquire_echo_surface (device_class, device_number, surface_nam< 

int device_class; 
int device_number; 
struct vwsurf *surface_name; 

inquire_echo_surf ace ( ) obtains the viewing surface on which echoing 
is done for the specified device. 

inquire_locator_2 ( locate r_number, x, y) 
int locator_number; 
float *x; 
float *y; 

inquire_locator_2 ( ) obtains the initial position of the specified LOCA- 
TOR in NDC space. 

Obtain Value and Range for inquire_valuator (valuator_number, initial_value, low, high) 
VALUATOR Device int valuator_number; 

float *initial_value; 
float *low; 
float *high; 

inquire_valuator ( ) obtains the value and range for the specified valuator 
device. 
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Obtain KEYBOARD 
Parameters 



Obtain STROKE Device 
Parameters 



inquire_k;eyboard (keyboard_number, buffer_size, initial_string, 
initial_cursor_position) 
int keyboard_number; 
int *buf fer_size; 
char *initial_string; 
int *initial_cursor_position; 

inquir e_keyboard ( ) obtains the size of the character buffer, the initial 
character string, and the initial character cursor for the specified KEYBOARD 
device. 

inquire_stroke (stroke_number, buffer_size, distance, time) 
int stroke_number; /* device number */ 
int *buf fer_size; /* not used */ 

float *distance; /* minimum distance to move in NDC */ 
int *time; /* not used */ 

inquire_stroke ( ) obtains the buffer size, distance, and time parameters for 
the specified STROKE device. 
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Deviations from ACM SIGGRAPH 

Core 

This appendix points out specific differences between the SunCore graphics 
package and the ACM SIGGRAPH Core Specification. In addition to differences 
noted here, SunCore has numerous extensions to the ACM Core which are docu- 
mented in the main body of this manual. 

A.l. Unimplemented Here is a list of those functions which SunCore does not implement: 

Functions 

T able A- 1 U nimplemented Primitive Attribute Functions 

Primitive Attribute Functions 

set_char just 
inquire_char just 



T able A-2 Unimplemented Synchronous / nput Functions 



Synchronous Input Functions 


await stroke 3 


inquire_pick 


initialize group 


inquire_stroke dimension 


inquire button 


set all buttons 


inquire_echo_segments 


set_button 


inquire input capabilities 


set_echo_segment 


inquire_input_device_charact eristics 


set_locator_3 


inquire locator_3 


set locport 2 


inquire locator dimension 


set_locport_3 


inquire locport 2 


terminate group 


inquire_locport_3 
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T able A-3 Unimplemented Asynchronous Input Functions 



Asynchronous Input Functions 


enable_device 


enable group 


disable_device 


disable_group 


disable all 


read_locator_2 


read_locator_3 


read_valuator 


await_event 


f lush_device_events 


flush_group_e vents 


flush_all_events 


associate 


disassociate 


disassociate_device 


disassociate_group 


disassociate_all 


get_pick_data 


ge t_k e yb o a r d_da t a 


get_stroke_data_2 


get stroke data 3 


get locator data 2 


get locator data 3 


get_valuator_data 


inquire device associations 


inquire_device status 



Table A-4 Unimplemented Control Functions 



Control Functions 


inquire output_capabilities 


inquire_selected_sur faces 


set irranediate_visibility 


make_picture_current 


inquire_control_status 


set_visibilities 


log error 





T able A-5 U nimplemented Escape Functions 

Escape Functions 

escape 

inquire_e scape 



A.2. Other Differences The sections that follow describe other differences between the Core 

specification and SunCore. 

Text SunCore does not have the charplane primitive attribute; instead, the charpath, 

champ, and charspace attributes are used to specify text orientation as described 
in the manual. The current release of SunCore has no STROKE precision text 
and no text justification. The inquire_text_extent_2 ( ) and 
inquire_text_extent_3 ( ) functions do not take a view surface name as 
an argument. The text inquiry functions only return meaningful values when the 
current charprecision attribute is CHARACTER. 

Raster Extensions SunCore contains several of the proposed raster extensions to the ACM Core and 

other raster functions. Thus there are no color or intensity primitive attributes. 
Instead a color lookup table model is used. There are several primitive attributes 
which are indices into lookup tables. In addition, hidden surfaces are supported 
on color view surfaces. This requires a second parameter to the 
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initialize view surface () function. 



Miscellaneous 



SunCore adds these functions: 



Table A-6 SunCore Extensions 



SunCore Extension Functions 

set_image_translate_3 
i nqu i r e_image_t r an s 1 a t e_3 
set_segment_image_translate_3 
i nqu i r e_s e gme nt_image_t r a n s 1 at e_3 



Table A-7 SunCore Replacements 



Core Function 



set_primitive_attributes_2 

set__primitive_attributes_3 

inquire_pr iinitive_attributes_2 
inquire primitive attributes 3 



SunCore Replacement 



set_pr imit i ve_att r ibut e s 



inquire primitive attributes 




Default values for many SunCore system parameters differ from those of the 
ACM Core. 

There are restrictions on set_world_coordinate_matrix_2 ( ) and 
set_world_coordinate_matrix_3 ( ) as described in the manual. 

As described in the manual, some of the echo types for input functions in the 
ACM Core are not implemented. 

The marker symbol primitive attribute deviates from the ACM Core as described 
in the manual. 

Batching of updates only applies to dynamic segment attributes as described in 
the manual. 

View surfaces initialized for hidden-surface elimination do not support dynamic 
segment attributes of highlighting, transformation, or translation. 
initialize_view_surf ace ( ) can optionally suppress clearing the view 
surface when it is initialized. 



microsystems 



Revision A, of 9 May 1988 

















SunCore View Surfaces 



SunCore View Surfaces 



B.l. The vwsurf Structure 

B.2. View Surface Types 

B.3. Choosing a View Surface Type within an Application Program 

Using Shell Variables to Determine the Environment 

The get_view_surf ace Function 

B.4. Specifying a View Surface for Initialization 

View Surface Specification for Raw Devices 

View Surface Specification for Window Devices 

B.5. Input Considerations 

B.6. Notes on Window Device View Surfaces 




SunCore View Surfaces 



SunCore supports several types of view surfaces and multiple simultaneous 
instances of any type, subject to the hardware resources of the workstation on 
which a SunCore program is being run. The current release allows up to five 
view surfaces to be active at any time. This appendix gives implementation 
details of SunCore view surfaces and provides information on initializing them. 

View surface names in SunCore are structures. The following declaration and 
definitions are contained in the header file <usercore . h>: 

#define DEVNAMESIZE 20 

struct vwsurf { 

char screenname [DEVNAMESIZE] ; 

char windowname [DEVNAMESIZE] ; 

int windowfd; 

int (*dd)(); 

int instance; 

int cmapsize; 

char cmapname [DEVNAMESIZE] ; 
int flags; 
char **ptr; 

}; 



#define NULL_VWSURF 0, 0, 0, 0, 0, 0} 

#define DEFAULT_VWSURF (ddname) \ 

0, ddname, 0, 0, 0, 0} 

#define VWSURF_NEWFLG 1 

After initialization via the function initialize_view_surf ace ( ) , a 
vwsurf structure represents a specific instantiation of a particular type of view 
surface. The elements of the vwsurf structure completely characterize that 
instantiation and/or provide information used to initialize the view surface. This 
appendix refers to members of the vwsurf structure using the standard C nota- 
tion, as if the declaration 

struct vwsurf vwsurf; 

had been given. 

vwsurf. screenname 

is a character string which is the name of the physical device on which the 
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view surface appears (for example, IdevIcgoneO). 
vwsurf.windowname 

is a character string which is the name of a window device which has been 
opened for display of the output primitives directed to the view surface (for 
example, IdevfwinlO). 

vwsurf.windowfd 

is the file descriptor corresponding to this device. Since, for all current Sun- 
Core view surface types, output display and input device echoing are accom- 
plished through window system functions, these members of the structure 
are valid even for raw output devices. 

vwsurf.dd 

is the name of the device-independent/device-dependent interface function 
through which graphics output to the view surface will pass. This function 
defines the view surface type. The current SunCore view surface types are 
described below. 

vwsurf. instance 

identifies the instantiation of a view surface type. It should be set to 0 prior 
to calling initialize_view_surf ace ( ) . SunCore will set this value 
appropriately if the initialization is successful. 

vwsurf. cmapsize 

defines the size of the color lookup table for the view surface, and the char- 
acter string vwsurf. cmapname gives its name, which can be used to share a 
color map between two or more view surfaces on the same physical device. 
These elements of the vwsurf stmcture are used only for view surfaces on 
color devices. Their use is described more fully below. 

vwsurf.flags 

is a ^eld of one-bit flags. Currently, only one flag, VWSURF NEWFLG, is 
defined; this flag is described below. 

vwsurf.ptr 

is a pointer to an array of character pointers. The array should be terminated 
by a null pointer. The strings pointed to by the array contain optional infor- 
mation which may be used to initialize the view surface. Details are pro- 
vided below. 



B.2. View Surface Types A view surface type in SunCore is the name of the driver function for the 

device-independent/device-dependent interface. The name of the function 
corresponding to the desired view surface type should be put into vwsurf.dd prior 
to calling initialize_view_surf ace ( ) (see the programming examples 
in Chapters 1 and 8). 

The current release of SunCore has eight view surface types: 
bwldd 

The Sun-1 monochrome bitmap display used as a raw device. 
bwldd 

The Sun-2 or Sun-3 monochrome bitmap display used as a raw device. 
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cgldd 

The Sun-1 color graphics display used as a raw device. 
cgldd 

The Sun-2 or Sun-3 color graphics display used as a raw device. 
cg4dd 

The Sun-3/1 10 color display used as a raw device. 
pixwindd 

A monochrome (one bit deep) graphics window within the Simtools window 
environment. This window may appear on either a color or monochrome 
display. 

cgpixwindd 

A color graphics window within the Suntools window environment. This 
window must appear on a color display. 

gpldd 

A Sun-2/ 160 or Sun-3/ 160 graphics display with a Graphics Processor 
option. 

gplpixwindd 

A color graphics window within the Suntools window environment mnning 
on a Sun-2/ 160 or Sun-3/ 160 color graphics display with a Graphics Proces- 
sor option. 

Only view surface types cgldd, cgldd, cg4dd, cgpixwindd, gpldd, and 
gplpixwindd support hidden surface removal. In the discussion above, gray scale 
devices are considered to be color devices. 

The term ‘raw device’ above implies that the physical device specified by 
vwsurf. screenname is used completely and only for display of graphics output 
directed to one view surface. This allows somewhat more efficient display of 
output primitives. It also implies that the user has not started up a Suntools win- 
dow environment using the device as a desktop. 

Low-level device-dependent functions are not part of SunCore. For efficiency, 
such functions are necessary for some applications. The Pixrect Reference 
Manual contains information on low-level functions corresponding to bwldd, 
bw2dd, cgldd, cg2dd cg4dd and gpldd, (the ‘pixrect’ level) and 
pixwindd, cgpixwindd and gplpixwindd (the ‘pixwin’ level). 

B.3. Choosing a View 
Surface Type within 
an Application 
Program 



It may be desirable to write application programs which use different view sur- 
face types depending on the environment. The next two subsections provide 
examples of ways to do this. The next subsection illustrates using a Shell vari- 
able, and the subsection after that uses the get_view_surf ace ( ) function to 
do the job in a more general way. The source for get_view_surf ace ( ) is 
contained in /usr/ src/sun/suntool/get_view_surface . c. 
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Using Shell Variables to Examining a Shell environment variable is one way to determine which environ- 

Determine the Environment ment a program is running in. The following example illustrates using either a 

bw2dd (raw Sun-2 or Sun-3 monochrome display) or a pixwindd (monochrome 
window) view surface depending on whether the user is currently in the Suntools 
window environment. The WINDOW ME environment variable is normally 
defined in die user’s environment if and only if the window system is being used. 

Figure B - 1 Selecting a View Surface from an Environment Variable 




The SunCore library includes the get_view_surf ace ( ) function which a 
programmer can use to set up a view surface structure using information from 
command-line arguments and the environment. A complete listing of 
get_view_surf ace ( ) appears at the end of this section. 
get_view_surface ( ) has the following declarations for C, FORTRAN, and 
Pascal: 



The get_view_surf ace 

Function 
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Table B-1 Declarations of get_view_sur f ace in C, FORTRAN, and Pascal 



Language 


Declaration 


C 


get view surface (vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 


FORTRAN 


getviewsurf ace (vwsurf) 
integer vwsurf (VWSURFSIZE) 


Pascal 


getviewsurf ace (var surf acename : 
vwsurf) : integer; external; 



The elements of argv are pointers to null-terminated strings which are extracted 
from the command line that started the application program. The following frag- 
ment of C code illustrates the use of get_view_sur f ace ( ) for C programs: 

Figure B-2 get_view_surface Example 



main(argc, argv) 
int argc; 
char **argv; 

{ 

struct vwsurf vwsurf; 



code 



if (get_view_surface (& vwsurf , argv)) 
exit (1) ; 

initialize_view_surf ace (Svwsurf , FALSE) ) 



more code 



} 

^ > 



get_view_surf ace ( ) returns zero (0) if it succeeds and non-zero otherwise. 
The vwsurf structure will have vwsurf.dd and possibly vwsurf.screenname set 
to appropriate values. Other elements of the structure will be null — the pro- 
grammer may modify them to suit the application, but it is not necessary. 

The only command-line option that get_view_surf ace ( ) currently recog- 
nizes is the display _device—d.I option, where display device is the name of the 
physical display device {Idevifb or IdevIcgoneO for example). The vwsurf 
structure will be set up to run on this device. get_view_surf ace ( ) also 
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determines if the window system is running on the device, and chooses vwsurf.dd 
appropriately. 

Using get_view_surf ace ( ) has a disadvantage in that since it refers to all 
six SunCore types of view surfaces, any program using it will get the code for all 
six device-independent/device-dependent driver functions linked in. For this rea- 
son, the code for get_view_surf ace ( ) is included here. SunCore program- 
mers may wish to tailor a version of this code for particular machine 
configurations and applications in order to make smaller final object code. 

The code of get_view_surf ace ( ) contains calls on several functions from 
lib sun window .a — the SunView library. Details of these functions can be 
found in the SunView Programmer’ s Guide and SunView System Programmer’ s 
Guide. 

Figure B-3 get_view_surf ace . c Module 

/* 

get_view_surf ace — Determines from command-line arguments and 
the environment a reasonable view surface 
for a SunCore program to run on. 

*/ 

♦include <sunwindow/window_hs .h> 

♦include <sys/file.h> 

♦include <sys/ioctl .h> 

♦include <sun/fbio.h> 

♦include <stdio.h> 

♦include <usercore.h> 

int bwlddO; /* All device-independent/device-dependent */ 

int bw2dd() ; /* routines are referenced in this function. */ 

int cglddO; /* This means the linker will pull in all of them */ 

int cg2dd(); 
int gplddO ; 
int pixwinddO ; 
int cgpixwindd ( ) ; 
int gplpixwindd () ; 

static struct vwsurf nullvs = NULL_VWSURF; 

static char *devchk; 
static int devhaswindows ; 

int get_view_surface (vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

{ 

int devfnd, fd, chkdevhaswindows () ; 
char *wptr, dev [DEVNAMESIZE] , *getenv(); 
struct screen screen; 
struct fbtype fbtype; 
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*vsptr = nullvs; 
devfnd = FALSE; 
if (argv) 

/* 

If command-line arguments are passed, process them using 
win_initscreenf romargv (see the Programmer's Reference Manual 
for the Sun Window System) . The only option used by 
get_view_surface is the -d option, allowing the user to 
specify the display device on which to run. 

*/ 

{ 

win_initscreenf romargv (Sscreen, argv) ; 
if (screen . scr_fbname [0] != ' ') 

{ 

/* -d option was found */ 
devfnd = TRUE; 

strncpy(dev, screen . scr_fbname, DEVNAMESIZE) ; 

/* 

Check to see if this device has a window system 
running on it. If so devhaswindows will be TRUE 
following the call to win_enumall . win_enumall is 
a function in libsunwindow . a . It takes a function 
as its argument, and applies this function to every 
window being displayed on any screen by the window 
system. To do this it opens each window and passes 
the windowfd to the function. The enumeration 
continues until all windows have been tried or the 
function returns TRUE. 

*/ 

devchk = dev; 
devhaswindows = FALSE; 
win_enumall (chkdevhaswindows) ; 

} 

} 

if ( ! devfnd) 

/* No -d option was specified */ 
if (wptr = getenv ("WINDOW_ME") ) 

{ 

/* 

Running in the window system. Find the device from 
which this program was started. 

*/ 

devhaswindows = TRUE; 

if ( (fd = open(wptr, 0_RDWR, 0)) < 0) 

{ 

fprintf (stderr, "get_view_surf ace : Can't open %s\n", 
wptr) ; 
return (1) ; 

} 

win_screenget (fd, Sscreen) ; 
close (fd) ; 

strncpy(dev, screen . sc r_fbname, DEVNAMESIZE); 

} 
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else 

{ 

/* 

Not running in the window system. Assume device is 
/dev/fb. 

*/ 

devhas windows = FALSE; 

strncpy(dev, "/dev/fb", DEVNAMESIZE) ; 

} 

/* Now have device name. Find device type. */ 
if ( (fd = open (dev, 0_RDWR, 0)) < 0) 

{ 

fprintf (stderr, "get_view_surf ace : Can't open %s\n", dev) ; 
return (1) ; 

} 

if (ioctKfd, FBIOGTYPE, Sfbtype) == -1) 

{ 

fprintf (stderr, "get_view_surface : ioctl FBIOGTYPE failed on %s\n", 
dev) ; 

close (fd) ; 
return (1) ; 

} 

close (fd) ; 

/* Now have device type and know if window system is running on it . */ 
if (devhas windows) 

switch (fbtype . fb_type) 

{ 

case FBTYPE_SUN1BW: 
case FBTYPE_SUN2BW: 

vsptr->dd = pixwindd; 
break; 

case FBTYPE_SUN1C0L0R: 
case FBTYPE_SUN2COLOR: 

vsptr->dd = cgpixwindd; 
break; 

case FBTYPE_SUN2GP : 

vsptr->dd = gplpixwindd; 
break; 
default : 

fprintf (stderr, 

"get_view_surf ace : %s is unknown fbtype\n", dev); 
return (1) ; 

} 

else 

switch (fbtype . fb_type) 

{ 

case FBTYPE_SUN1BW: 

vsptr->dd = bwldd; 
break; 

case FBTYPE_SUN2BW: 

vsptr->dd = bw2dd; 
break; 

case FBTYPE SUNICOLOR: 
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vsptr->dd = cgldd; 
break; 

case FBTYPE_SUN2C0L0R: 
vsptr->dd = cg2dd; 
break; 

case FBTYPE_SUN2GP : 

vsptr->dd = gpldd; 
break; 
default : 

fprintf (stderr, 

"get_view_surf ace : %s is unknown fbtype\n", dev) ; 
return (1) ; 

} 

/* Now SunCore device driver pointer is set up. */ 
if ( ! devhaswindows 1 | devfnd) 

/* 

If no window system on device or -d option was specified, 
tell SunCore which device. Otherwise, let SunCore figure 
out the device itself from WINDOW_GFX so the default 
window will be used if desired. 

*/ 

strncpy (vsptr->screenname, dev, DEVNAMESIZE) ; 
return (0 ) ; 

} 

static int chkdevhaswindows (windowfd) 
int windowfd; 

{ 

struct screen windowscreen; 

win_screenget (windowfd, &windowscreen) ; 
if (strcmp (devchk, windowscreen . scr_fbname) == 0) 

{ 

/* 

If this window is on the display device we are checking, set 
the flag TRUE. Return TRUE to terminate the enumeration. 

*/ 

devhaswindows = TRUE; 
return (TRUE) ; 

} 

return (FALSE) ; 

} 



B.4. Specifying a View 
Surface for 
Initialization 
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It is not necessary to specify every member of the vwsurf structure in order to 
initialize the view surface. If only vwsurf. dd is specified, SunCore will try to 
obtain a view surface of the specified type according to a default sequence. A 
statically allocated vwsurf structure may be set up to use this default by initial- 
izing the structure via the DEFAULT_ VWSURF macro defined in 
<usercore . h>. This is a compile-time initialization. The user may exercise 
finer control over view surfaces by setting other elements of the structure as 
described below. Any members which are not specified by the user should be set 
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to zero (the integer 0, the NULL pointer, or an empty string, as appropriate). 



View Surface Specification for 
Raw Devices 



The default action for obtaining a new view surface of a raw device type is to try 
to open a sequence of devices until one is found which is of the right type and is 
not already being used. The sequence always starts with Idevlfb. Then the fol- 
lowing names are tried depending on the view surface type: 



bwldd 

bw2dd 

cgldd 

cg2dd 

cg4dd 

gpldd 



”/dev/bwoneO”, 

” /dev/bwtwoO " , 

" /dev/ cgoneO ” , 

" /dev/cgtwoO ” , 

"/dev/cgfourO", 

"/dev/gponeOa", 



"/dev/bwonel", . 
"/dev/bwtwol", . 
”/dev/cgonel", . 
"/dev/cgtwol", . 
" / dev/cgf our 1 ” , 
" /dev/gponeOb " , 



, ”/dev/bwone9" 

, "/dev/bwtwo9" 

, "/dev/cgone9” 

, ”/dev/cgtwo9" 

”/dev/cgf our9" 
. . , ” / dev/gpone3d" 



If none of the names in the sequence can be successfully opened and verified to 
be of the correct type and not already in use, 
initialize_view_surf ace ( ) fails. 

If the user wishes to specify a particular physical device for a view surface, he 
may set vwsurf. screenname to be the device name of that device. The same steps 
will be taken to try to open the device as for each name in the default sequence. 
However, if these steps fail, no other names will be tried, and the initialization 
will fail. 



vwsurf.cmapname and vwsurf.cmapsize are only used for color view surfaces. 

For cgldd, cg2dd, cg4dd and gpldd vwsurf.cmapsize is set to 256. If 
vwsurf.cmapname is specified, this name is used as the name of the color map; 
otherwise SunCore will provide a unique name. 

No flags are currently defined for use with raw devices. 

vwsurf.ptr provides a mechanism for passing optional initialization data to Sun- 
Core. In the case of raw devices, one such option is currently available — the 
passing of information about the adjacencies of physical screens. When the user 
creates a Suntools window environment on a screen, he is also responsible for 
specifying the relationship of that screen to other screens also running Suntools 
for purposes of tracking the mouse across multiple screens. The adjacentscreens 
command may be used to do this (see the SunOS Reference Manual). However, 
when a SunCore program initializes a new view surface on a raw screen, the user 
will not previously have been able to inform the system of this adjacency 
because the new screen was previously not in use. vwsurf.ptr may be used to 
pass adjacency information for the new screen. 

If vwsurf.ptr is not NULL, it should point to an array of character pointers. Only 
the first pointer in this array will be used. It should point to a string which is the 
pathname of a file containing information about the adjacencies of physical 
display devices. When the user sets up his display devices on his desk he may 
create a file describing the layout of these devices. For example, the following 
lines describe a system with two screens, the console frame buffer on the left 
(which might be a monochrome bitmap display) and a Sun color graphics display 
on the right: 
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/dev/fb 

R: /dev/cgoneO 
/dev/cgoneO 
L: /dev/fb 

By convention, Idevifb is the console frame buffer and IdevIcgoneO is the first 
Sun color graphics display on a system. For each display device in the system, 
there should be one line giving its name, followed by several lines giving the 
directions and names of all adjacent screens. Thus all four lines above are neces- 
sary, not just the first two. Directions may be indicated as R, L, T, and B for 
right, left, top, and bottom, or as N, S, E, and W for north, south, east, and west. 



View Surface Specification for The default action for obtaining a new view surface of type pixwindd. 

Window Devices cgpixwindd or gplpixwindd is to first test whether the window referred to by the 

Shell environment variable WINDOW GFX is already in use as a view surface. If 
not, a blanket window is inserted over the WINDOW GFX window and this 
blanket window becomes the view surface. If WINDOW_GFX has already been 
used in this maimer, the program /usr/lib/view_surf ace is invoked to 
create a new window on the same physical display device as WINDOW GFX. 

This new window becomes the view surface. Thus, if a SunCore program is mn 
from the tty subwindow of a Graphics Tool, the first default view surface will 
occupy the display space covered by the gra{diics subwindow of the tool. Subse- 
quent default view surfaces will appear as graphics windows, each within a 
separate View Surface Tool on the same screen as the Graphics Tool. 

This default action may be circumvented in two ways. If vwsurf. flags has the 
VWSURF NEWFLG set, no attempt is made to take over WINDOW GFX. A new 
window within a View Surface Tool is opened on the same screen as 
WINDOW GFX. If vwsurf. screenname is non-empty, a new window within a 
View Surface Tool is opened on the screen specified by vwsurf. screenname, pro- 
vided this device exists and has a Suntools window enviromnent running on it. 

For view surfaces of type cgpixwindd or gplpixwindd, vwsurf.cmapsize 
and vwsurf. cmapname provide a means of specifying and sharing color maps. 

The color map facilities of SunView are used to control color maps for 
cgpixwindd or gplpixwindd view surfaces (see the SunView 
Programmer* s Guide). The user may specify a color map size of 0, in which 
case a color map of length 2 will be used. Otherwise, vwsurf.cmapsize should be 
a power of 2 between 2 and 256. The user may specify a null color map name, in 
which case SunCore will provide a unique name. Otherwise, SunCore will check 
vwsurf. cmapname against the names of the color maps for all windows currently 
displayed on the physical device on which the new view surface is to appear. If a 
matching name is found, that color map will be used (even if its size differs from 
vwsurf.cmapsize) and this map is shared among all windows on the device which 
reference that name. If the user specified a null name or the specified name does 
not match any current window’s color map name, a new color map is allocated 
with the given size. The indices for each cgpixwindd or gplpixwindd view 
surface’s color map run from 0 to vwsurf.cmapsize— \. 

Currently, one optional string of initialization data may be passed to 
initialize_view_surf ace ( ) . If vwsurf.ptr is non-NULL, it should 
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point to an array of character pointers, only the first of which will be used. The 
pointer should point to a string containing position and size information for a 
Core Tool which may be started up to provide a window for the new view sur- 
face. (If the WINDOW GFX window is taken over by this new view surface and 
thus no View Surface Tool is started, the string will be ignored.) The string 
should consist of nine integers, separated by commas: 

”nl, nt,nw,nh, il, it, iw, ih, I" 

nl, and nt give the initial position of the top left comer of the View Surface Tool 
in its normal form, nw and nh give the initial width and height The numbers are 
given in screen coordinates, where (0, 0) is the upper left comer, il, it, iw, and ih 
give the same initial information for the iconic form of the tool. I is a boolean 
flag which should be non-zero if the tool is to be started in its iconic form. 

B.5. Input Considerations SunCore uses window system functions to obtain user input from the keyboard 

and mouse, no matter what mix of raw device view surfaces and window device 
view surfaces the user has initialized. For purposes of input, a raw device view 
surface behaves just like a window device view surface; it exists as a window 
within the window system’s data stmctures, and the user may direct input to the 
window simply by positioning the mouse over it. The facts that window system 
input is directed to different windows depending on the location of the mouse 
and that the mouse position in the window system is reported in the coordinates 
of the window underlying the mouse have implications for the SunCore input 
functions. 

For SunCore programs which are invoked from a window within the Suntools 
window environment, whenever the ICEYBOARD device is initialized, 
await_keyboard ( ) will return characters typed when the mouse is located 
over any initialized view surface (belonging to a single user process) or over the 
tty subwindow from which the program was started. For programs run from out- 
side a window environment, await keyboard will return all characters typed on 
the keyboard, provided the KEYBOARD device is initialized. 

The ACM Core specification defines input and output to be completely orthogo- 
nal functions. Thus, it is possible to initialize a locator device and read from it 
without ever initializing a view surface. SunCore uses the mouse as the LOCA- 
TOR, STROKE, PICK, VALUATOR, and BUTTON devices. The only way Sun- 
Core can obtain mouse position and button click information to emulate these 
logical devices is to take input from a window. SunCore will return valid data in 
response to input requests for the LOCATOR, STROKE, PICK, and VALUATOR 
devices only when the user has associated these devices with an initialized view 
surface via the set_echo_surface ( ) function. Because all SunCore view 
surfaces are instantiations of generic view surface types, there is no default echo 
surface for any input device. The set_echo_surf ace ( ) function will 
accept a NULL pointer as its surface name argument to allow the programmer to 
end the association of an input device with a view surface. Any input device 
may be echoed on any view surface independently of any other input device. 

The input functions await_any_button_get_locator_2 ( ) , 
await_stroke_2 ( ) , await_pick ( ) , and 
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await_any_button_get_valuator ( ) will only use mouse input which 
the user directs to the window which is the echo surface for the indicated LOCA- 
TOR, STROKE, PICK, or VALUATOR device. This includes both position and 
button click input, so that the functions which are terminated by button clicks 
will terminate only when a button click occurs within the proper window (or a 
timeout occurs). Which buttons are listened to is still controlled by individually 
initializing or terminating each BUTTON device. 

The user may also use set_echo_surf ace ( ) to choose from which window 
button clicks should be reported for a BUTTON device when the 
await_button ( ) function is called; alternatively, if the echo surface for a 
BUTTON device is NULL, await_button ( ) will check for button clicks from 
any view surface associated with a LOCATOR, STROKE, PICK, or VALUATOR 
device. 

Note that the resolution obtained from a LOCATOR, STROKE, PICK, or VALUA- 
TOR device is limited by the width and/or height of its echo surface window, 
since mouse position information is provided by window system input functions 
in terms of window coordinates. 

B.6. Notes on Window Graphics primitives drawn on a view surface as part of a temporary segment nor- 

Device View Surfaces mally remain visible on the view surface until a new-frame action occurs. For 

view surfaces which are windows within the Suntools window environment, 
several user actions can cause the view surface to be redrawn. Such actions 
include stretching the enclosing tool, exposing a previously obscured portion of 
the tool, and changing from the iconic form of the tool to the normal form. 

When the view surface is redrawn in this maimer, all output primitives which 
previously appeared as part of temporary segments will disappear. 

When a SunCore program is run from a she 11 tool { 1 ) , WINDOW GFX is 
normally set to be the tool’s tty subwindow. If this window is taken over and 
blanketed to serve as a view surface, output directed to the tty subwindow (for 
example, stdout and stderr, including SunCore error messages) will not be visible 
because the blanket window obscures the tty subwindow. When the program ter- 
minates or the view surface is terminated, any portion of this output which has 
not scrolled out of the subwindow will be visible. The fact that the tty subwin- 
dow is obscured also means that there is no way to type characters to that win- 
dow, so that stdin will never see any input However, if the KEYBOARD device 
is initialized, special characters, such as interrupt and suspend, typed to the 
blanket window will be recognized and will have their normal effect on the user 
process. 
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This appendix contains an alphabetical list of SunCore functions and their argu- 
ments definitions. SunCore programs written in C must contain the statement: 

#include <usercore.h> 

at the start of each SunCore source file. 

C.l. Alphabetical List of C The list on the following pages is a complete alphabetical list of the functions in 
Functions SunCore. 

allocate_raster (rptr) 
struct { 

int width, height, depth; 
short *bits; 

} *rptr; 

await_any_button (tim, butnum) 
int tim; 
int *butnum; 

await_any_button_get_locator_2 (tim, locnum, butnum, x, y) 
int tim, locnum, *butnum; 
float *x, *y; 

await_any_button_get_valuator (tim, valnum, butnum, val) 
int tim, valnum, *butnum; 
float *val; 

await_keyboard(tim, keynum, string, length) 
int tim, keynum; 
char ^string; 
int *length; 

await_j)ick (tim, picknum, segnam, pickid) 
int tim; 

int picknum, *segnam, *pickid; 

await_stroke_2 (tim, strokenum, arrsize, xarray, yarray, numxy) 
int tim, strokenum, arrsize, *numxy; 
float xarray [], yarray []; 
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begin_batch_of_updates () 

close_retained_segment () 

close_temporary_segment ( ) 

create_retained_segment (segname) 
int segname; 

create_temporary_segment () 

def ine_color_indices (surf , il, i2^ red, grn, blu) 
struct vwsurf *surf; 
int il, i2; 

float *red, *grn, *blu; 

delete_all_retained_segments () 

delete_retained_segment (segname) 
int segname; 

deselect_view_surface (surf name) 
struct vwsurf *surfname; 

end_batch_of_updates () 

f ile_to_raster ( rasf id, raster, map) 
int rasfid; 
struct { 

int width, height, depth; 
short *bits; 

} *raster; 
struct { 

int type, nbytes; 
char *data; 

} *map ; 

f ree_raster (rptr) 
struct { 

int width, height, depth; 
short *bits; 

} *rptr; 

get_mouse_state (devclass, devnum, x, y, buttons) 
int devclass, devnum; 
float *x, *y; 
int *buttons; 

get_raster (surfname, xmin, xmax, ymin, ymax, xd, yd, raster) 
struct vwsurf *surfname; 

float xmin, ymin, xmax, ymax; int xd, yd; 
struct { 

int width, height, depth; 
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short *bits; 

} *raster; 

get_view_surface (vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

initialize_core (outlev, inlev, dim) 
int outlev, inlev, dim; 

initialize_device (devclass, devnum) 
int devclass, devnum; 

initialize_view_surf ace (surfname, type) 
struct vwsurf *surfname; 
int type ; 

inquire_char just (chjust) 
int *chjust; 

inquire_charpath_2 (dx, dy) 
float *dx, *dy; 

inquire_charpath_3 (dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_charprecision (chqualty) 
int *chqualty; 

inquire_charsize (chwidth, cheight) 
float *chwidth, *cheight; 

inquire_char space (space) 
float *space; 

inquire_charup_2 (dx, dy) 
float *dx, *dy; 

inquire_charup_3 (dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_color_indices (surf , il, i2, red, grn, blu) 
struct vwsurf *surf; 
int il, i2; 

float *red, *grn, *blu; 

inquire_current_position_2 (x, y) 
float *x, *y; 

inquire_current_position_3 (x, y, z) 
float *x, *y, *z; 

inquire_detect ability (detectability) 
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int ^detectability; 

inquire_echo (devclass, devnum, echotype) 
int devclass, devnum, *echotype; 

inquire_echo_position (devclass, devnum, x, y) 
int devclass, devnum; 
float *x, *y; 

inquire_echo_surf ace (devclass, devnum, surfname) 
int devclass, devnum; 
struct vwsurf * surfname; 

inquire_fill_index (color) 
int *color; 

inquire_font (font) 
int *font; 

inquire_highlighting (highlighting) 
int *highlighting; 

inquire_image_transformation_2 (sx, sy, a, tx, ty) 
float *sx, *sy, *a, *tx, *ty; 

inquire_image_transformation_3 (sx, sy, sz, ax, ay, az, tx, ty, tz) 
float *sx, *sy, *sz, *ax, *ay, *az, *tx, *ty, *tz; 

inquire_image_t rans format ion_type (segtype) 
int * segtype; 

inquire_image_translate_2 (tx, ty) 
float *tx, *ty; 

inquire_image_translate_3 (tx, ty, tz) 
float *tx, *ty, *tz; 

inquire_inverse_composite_matrix (arrayptr) 
float *arrayptr; 

inquire_keyboard (keynum, bufsize, istr, pos) 
int keynum, *bufsize, *pos; 
char *istr; 

inquire_line_index (color) 
int *color; 

inquire_linestyle (linestyl) 
int *linestyl; 

inquire_linewidth (linwidth) 
float *linwidth; 
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inquire_locator_2 (locnum, x, y) 
int locnum; 
float *x, *y; 

inquire_marker_symbol (mark) 
int *mark; 

inqpiire_ndc_space_2 (width/ height) 
float * width/ ^height; 

inquire_ndc_space_3 (width/ height/ depth) 
float *width/ *height/ *depth; 

inquire_open_retained_segment (segname) 
int * segname; 

inqu i re_open_t empo r a r y_segment ( open ) 
int *open; 

inquire_pen (pen) 
int *pen; 

inquire_j3ick_id (pickid) 
int *pickid; 

inquire_j>olygon_edge_style (polyedgstyl) 
int *polyedgstyl; 

inquire_polygon_interior_style (polyintstyl) 
int *polyintstyl; 

inquire^rimitive_attributes (defprim) 
struct { 

int lineindx/ fillindX/ textindx; 
int linestyl/ polyintstyl/ polyedgstyl; 
float linwidth; 
int pen/ font; 

float charwidth/ charheight; 

float charupx/ charupy/ charupz/ charupw; 

float charpathx/ charpathy/ charpathz/ charpathw; 

float charspacex/ charspacey/ charspacez/ charspacew; 

int chjust/ chqualty; 

int marker/ pickid/ rasterop; 

} *defprim; 

inquire_pro jection (pro jection_type/ dx_j5roj/ dy_proj/ dz_proj) 
int *pro jection_type; 

inquire_rasterop (rasterop) 
int *rasterop; 

inquire_retained_segment_names (listcnt/ seglist/ segcnt) 
int seglist []/ listcnt/ *segcnt; 
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inquire_retained_seginent_surfaces (segname, arraycnt, surfaray, surfnum) 
int segname, arraycnt; 
struct vwsurf surfaray[]; 
int * surfnum; 

inquire_segment_detectability (segname, detectbl) 
int segname; 
int *detectbl; 

inquire_segment_highlighting (segname, highlght) 
int segname ; 
int *highlght; 

inquire_segment_image_transformation_2 (segname, sx, sy, a, tx, ty) 
int segname; 

float *sx, *sy, *a, *tx, *ty; 

inquire_segment_image_t rans format ion_3 (segname, sx, sy, sz, rx, ry, rz, tx, ty, tz) 
int segname; 

float *sx, *sy, *sz, *rx, *ry, *rz, *tx, *ty, *tz; 

inquire_segment_image_translate_2 (segname, tx, ty) 
int segname ; 
float *tx, *ty; 

inquire_segment_image_translate_3 (segname, tx, ty, tz) 

int segname; 

float *tx, *ty, *tz; 

inc[uire_segment_visibility (segname, visbilty) 
int segname; 
int *visbilty; 

inquire_stroke (strokenum, bufsize, dist, time) 
int strokenum, *bufsize, *time; 
float *dist; 

inquire_text_extent_2 (s, dx, dy) 

char *s; 

float *dx, *dy; 

inquire_text_extent_3 (s, dx, dy, dz) 
char *s; 

float *dx, *dy, *dz; 

inquire_text_index (color) 
inf *color; 

inquire_valuator (valnum, init, low, high) 
int valnum; 

float *init, *low, *high; 

inquire_view_depth (f ront_distance, back_distance) 
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float *f ront_distance, *back_distance; 

inquire_view_plane_distance (view_distance) 
float *view_distance; 

inquire_view_plane_normal (dx_norm, dy_norm, dz_norm) 
float *dx_norm, *dy_nonn, *dz_nonn; 

inquire_view_reference_point (x_ref , y_ref, z_ref) 
float *x_ref, *y_ref, *z_ref; 

inquire_view_up_2 (dx_up, dy_up) 
float * dx_up , * dy_up ; 

inquire_view_up_3 (dx_up, dy_up, dz_up) 
float *dx_up, *dy_up, *dz_up; 

inquire_viewing_control_parameters (windowclip, f rontclip, backclip, type) 
int *windowclip, *frontclip, *backclip, *type; 

inquire_viewing__parameters (viewparm) 
struct { 

float vwrefpt[3]; 
float vwplnorm[3]; 
float viewdis; 
float frontdis; 
float backdis; 
int projtype; 
float projdir[3]; 
float window [4]; 
float vwupdir[3]; 
float viewport [6]; 

} *viewparm; 

inquire_viewport_2 (xmin, xmax, yinin, ymax) 
float *xmin, *xmax, *ymin, *ymax; 

inquire_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float *xmin, *xmax, *ymin, *ymax, *zmin, *zmax; 

inquire_visibility (visibility) 
int *visibility; 

inquire_window (umin, umax, vmin, vmax) 
float *umin, *umax, *vmin, *vmax; 

inquire_world_coordinate_matrix_2 (arr) 
float *arr; 

inquire_world_coordinate_matrix_3 (arrayptr) 
float *arrayptr; 

line_abs_2 (x, y) 
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float X, y; 

line_abs_3 (x, y, z) 
float X, Yr z; 

1 i ne_r e 1_2 ( dx , dy ) 
float dx, dy; 

line_rel_3 (dx, dy, dz) 
float dx, dy, dz; 

map_ndc_to_world_2 (ndcx, ndcy, wldx, wldy) 
float ndcx, ndcy, *wldx, *wldy; 

map_ndc_to_world_3 (ndcx, ndcy, ndcz, wldx, wldy, wldz) 
float ndcx, ndcy, ndcz, *wldx, *wldy, *wldz; 

map_world_to_ndc_2 (wldx, wldy, ndcx, ndcy) 
float wldx, wldy, *ndcx, *ndcy; 

map_world_to_ndc_3 (wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz, *ndcx, *ndcy, *ndcz; 

inarker_abs_2 (mx, my) 
float mx, my; 

marker_abs_3 (mx, my, mz) 
float mx, my, mz; 

marker_rel_2 (dx, dy) 
float dx, dy; 

marker_rel_3 (dx, dy, dz) 
float dx, dy, dz; 

move_abs_2 (x, y) 
float X, y; 

move_abs_3 (x, y, z) 
float X, y, z; 

move_rel_2 (dx, dy) 
float dx, dy; 

move_rel_3 (dx, dy, dz) 
float dx, dy, dz; 

new_f rame ( ) 

polygon_abs_2 (xlist , ylist, n) 
float *xlist, *ylist; 
short n; 
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polygon_abs_3 (xlist, ylist, zlist, n) 
float *xlist, *ylist, *zlist; 
int n ; 

polygon_rel_2 (xlist, ylist, n) 
float *xlist, *ylist; 
short n; 

polygon_rel_3 (xlist, ylist, zlist, n) 
float *xlist, *ylist, *zlist; 
int n; 

polyline_abs_2 (xcoord, ycoord, n) 
float xcoord[], ycoord[]; 
int n ; 

polyline_abs_3 (xcoord, ycoord, zcoord, n) 
float xcoord[], ycoord[], zcoord [] ; 
int n; 

polyline_rel_2 (xcoord, ycoord, n) 
float xcoord [], ycoord []; 
int n ; 

polyline_rel_3 (xcoord, ycoord, zcoord, n) 
float xcoord [], ycoord[], zcoord []; 
int n; 

polymarker_abs_2 (xcoord, ycoord, n) 
float xcoord[], ycoord[]; 
short n; 

polymarker_abs_3 (xcoord, ycoord, zcoord, n) 
float xcoord[], ycoord [], zcoord []; 
int n ; 

polymarker_rel_2 (xcoord, ycoord, n) 
float xcoord[], ycoord []; 
int n; 

polymarker_rel_3 (xcoord, ycoord, zcoord, n) 
float xcoord[], ycoord[], zcoord []; 
int n; 

print_error (string, error) 
char *string; 
int error; 

put_raster (srast) 
struct { 

int width, height, depth; 
short *bits; 

} *srast; 
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raster_to_file (raster, map, rasfid, n) 
struct { 

int width, height, depth; 
short *bits; 

} ^raster; 
struct { 

int type, nbytes; 
char *data; 

} *map; 

int rasfid, n; 

rename_retained_segment (segname, newname) 
int segname, newname; 

report_most_recent_error (error) 
int *error; 

restore_segment (segname, filename) 
int segname; 
char * filename; 

save_segment (segnum, filename) 
int segnum; 
char * filename; 

select_view_sur face (surf name) 
struct vwsurf *surfname; 

set_back_plane_clipping (onof f ) 
int onoff; 

set_char just (chjust) 
int chjust; 

set_charpath_2 (dx, dy) 
float dx, dy; 

set_charpath_3 (dx, dy, dz) 
float dx, dy, dz; 

set_charprecision (chqualty) 
int chqualty; 

set_charsize (chwidth, cheight) 
float chwidth, cheight; 

set_charspace (space) 
float space; 

set_charup_2 (dx, dy) 
float dx, dy; 

set_charup_3 (dx, dy, dz) 
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float dx, dy, dz; 

set_coordinate_system_type (type) 
int type; 

set_detect ability (detectability) 
int detectability; 

set_drag (drag) 
int drag; 

set_echo (devclass, devnum, echotype) 
int devclass, devnum, echotype; 

set_echo_group (class, devnuin, n, echotype) 
int class, devnum[], n, echotype; 

set_echo_position (devclass, devnum, x, y) 
int devclass, devnum; 
float X, y; 

set_echo_surf ace (devclass, devnum, surfname) 
int devclass, devnum; 
struct vwsurf *surfname; 

set_f ill_index (color) 
int color; 

set_font (font) 
int font; 

set_f ront_plane_clipping (onof f ) 
int onoff; 

set_highlighting (highlighting) 
int highlighting; 

set_image_transformation_2 (sx, sy, a, tx, ty) 
float sx, sy, a, tx, ty; 

set_image_transformation_3 (sx, sy, sz, ax, ay, az, tx, ty, tz) 
float sx, sy, sz, ax, ay, az, tx, ty, tz; 

set_image_trans format ion_type (type) 
int type; 

set_image_translate_2 (tx, ty) 
float tx, ty; 

set_image_translate_3 (tx, ty, tz) 
float tx, ty, tz; 

set_keyboard (keynum, bufsize, istr, pos) 
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int keynum, bufsize, pos; 
char *istr; 

set_light_direction (dx, dy, dz) 
float dx, dy, dz; 

set_line_index (color) 
int color; 

set_linestyle (linestyl) 
int linestyl; 

set_linewidth (linwidth) 
float linwidth; 

set_locator_2 (locnum, x, y) 
int locnum; 
float X, y; 

set_marker_symbol (mark) 
int mark; 

set_ndc_space_2 (width, height) 
float width, height; 

set_ndc_space_3 (width, height, depth) 
float width, height, depth; 

set_output_clipping (onof f ) 
int onoff; 

set_pen (pen) 
int pen; 

set_pick_id (pickid) 
int pickid; 

set_polygon_edge_style (polyedgstyl) 
int polyedgstyl; 

set_polygon_interior_style (polyintstyl) 
int polyintstyl; 

set_primitive_attributes (defprim) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polyintstyl, polyedgstyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 
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int chjust, chqualty; 

int marker, pickid, rasterop; 

} *defprim; 

set_pro jection (pro jtype, dx, dy, dz) 
int pro j type; 
float dx, dy, dz; 

set_rasterop (f lag) 
int flag; 

set_segment_detectability (segname, detectbl) 
int segname; 
int detectbl; 

set_segment_highlighting (segname, highlght) 
int segname; 
int highlght; 

set_segment_image_transformation_2 (segname, sx, sy, a, tx, ty) 
int segname; 

float sx, sy, a, tx, ty; 

set_segment_image_translate_2 (segname, tx, ty) 
int segname; 
float tx, ty; 

set_segment_image_translate_3 (segname, dx, dy, dz) 
int segname; 
float dx, dy, dz; 

set_segment_image_transformation_3 (segname, sx, sy, sz, rx, ry, rz, tx, ty, tz) 
int segname; 

float sx, sy, sz, rx, ry, rz, tx, ty, tz; 

set_segment_vis ibil it y (segname, visbilty) 
int segname ; 
int visbilty; 

set_shading_jDarameters (amb, dif , spec, flood, bump, hue, style) 
float amb, dif, spec, flood, bump; 
int hue, style; 

set_stroke (strokenum, bufsize, dist, time) 
int strokenum, bufsize, time; 
float dist; 

set_text_index (color) 
int color; 

set_valuator (valnum, init, low, high) 
int valnum; 

float init, low, high; 
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set_vertex_indices (indxlist, n) 
int * indxlist, n; 

set_vertex_normals (dxlist, dylist, dzlist, n) 
float *dxlist, *dylist, *dzlist; 
int n ; 

set_view_depth (near, far) 
float near, far; 

set_view_plane_distance (dist) 
float dist; 

set_view_plane_nonnal (dx, dy, dz) 
float dx, dy, dz; 

set_view_reference_point (x, y, z) 
float X, y, z; 

set_view_up_2 (dx, dy) 
float dx, dy; 

set_view_up_3 (dx, dy, dz) 
float dx, dy, dz; 

set_viewing_j>arameters (viewparm) 
struct { 

float vwrefpt [3] ; 
float vwplnorm [3] ; 
float viewdis; 
float frontdis; 
float backdis; 
int pro j type; 
float projdir[3]; 
float window [4]; 
float vwupdir[3]; 
float viewport[6]; 

} *viewparm; 

set_viewport_2 (xmin, xmax, ymin, ymax) 
float xmin, xmax, ymin, ymax; 

set_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float xmin, xmax, ymin, ymax, zmin, zmax; 

set_visibility (visibility) 
int visibility; 

set_window (umin, umax, vmin, vmax) 
float umin, umax, vmin, vmax; 

set_window_clipping (onof f ) 
int onoff; 
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set_world._coordinate_matrix_2 (array) 
float *array; 

set_world_coordinate_matrix_3 (array) 
float *array; 

set_zbuf fer_cut (surf, xarr, zarr, n) 
struct vwsurf *surf; 
float xarr[], zarr[]; 
int n ; 

size_raster (surfname, xmin, xmax, ymin, ymax, raster) 
struct vwsurf *surfname; 
float xmin, ymin, xmax, ymax; 
struct { 

int width, height, depth; 
short *bits; 

} *raster; 

terminate_core ( ) 

terminate_device (devclass, devnum) 
int devclass, devnum; 

terminate_view_surf ace (surf name) 
struct vwsurf *surfname; 

text (string) 
char *string; 
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Using SunCore with Fortran-77 

Programs 



All functions provided in SunCore may be called from FORTRAN-77 programs 
by linking them with the /usr/lib/libcore77 . a library. This is done by 
using the f77 compiler with a command line such as: 





% til -f switch -o grab grab.f -lcore77 -Icore -Isunwindow -Ipixrect -Im 

V > 



where grab . f is the FORTRAN source program. The -f switch option will 
cause the compiler to take advantage of floating point hardware if it is available. 
Otherwise, the compiler will emulate this floating point support with software. 
(For more information on floating point options, see Appendix F). Note that 
/usr/lib/libcore . a must be linked with the program (the —Icore 
option), and / usr/lib/libcore77 . a must come before it (the — lcore77 
option). 

Defined constants may be referenced in source programs by including 
/usr/include/f 77/usercore77 . h In a FORTRAN program, this must be 
done via a source statement like: 

include ”/usr/include/f 77/usercore77 .h" 

This include statement must be in each FORTRAN program unit which uses the 
defined constants, not just once in each source program file. The default primi- 
tive attribute structure PRIMATTS which is provided in <user core . h> and is 
described in section 6.1.23 of this manual is not provided in user core77 . h 
because of FORTRAN’S restrictions on the ordering of specification statements 
and data statements. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in 
length and may not contain the underline character. For this reason, FORTRAN 
programs must use abbreviated names to call the corresponding SunCore func- 
tions. The correspondence between the full SunCore names and the FORTRAN 
names appears later in this appendix. In addition, FORTRAN-77 declarations for 
all SunCore functions appear at the end of this appendix. 
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D.l. Programming Tips 



□ The abbreviated names of the SunCore functions are less readable than the full 
length names because the underline character cannot be used in the FORTRAN 
names. However, since FORTRAN doesn’t distinguish between upper-case and 
lower-case letters in names, upper-case characters can be used to improve rea- 
dability. There is an example of this later in this appendix. 

□ Character strings passed from FORTRAN programs to SunCore cannot be 
longer than 256 characters. 

□ FORTRAN passes all arguments by reference. Although some SunCore func- 
tions receive arguments by value, the FORTRAN programmer need not worry 
about this. The interface routines in /usr/lib/libcore77 . a handle this 
situation correcdy. When in doubt, look at the FORTRAN declarations for 
SunCore subroutines at the end of this appendix. 

□ SunCore uses pointers in some places. For instance, view surface structures 
contain pointers to device driver functions. Also, the raster data type includes 
a pointer to an array of short’s containing the raster data. There are no pointer 
types in FORTRAN, but there are ways to handle all uses of pointers required 
to use SunCore. For view surface names, the following fragments of C code 
and FORTRAN code do the same thing: 



Table D- 1 Comparison of C and FORTRAN Statements 



C Code 


FORTRAN Code 


struct vwsurf vsurf = NULL_VWSURF; 


integer vsurf (VWSURFSIZE) 


int bwldd 0; 


integer bwldd 




external bwldd 


vsurf. dd = bwldd; 


data vsurf /VWSURFSIZE*0/ 




vsurf (DDINDEX) = loc (bwldd) 


initialize_view_surf ace (&vsurf , FALSE) ; 


call InitializeVwsurf (vsurf , FALSE) 



The constants VWSURFSIZE and DDINDEX are defined in 
usercore7 7 . h. The constant VWSURFNEWFLG is also defined in 
usercore77 . h. 

bwldd 

The Sun-1 monochrome bitmap display used as a raw device. 
bw2dd 

The Sun-2 or Sun-3 monochrome bitmap display used as a raw device. 
cgldd 

The Sun-1 color graphics display used as a raw device. 
cg2dd 

The Sun-2 or Sun-3 color graphics display used as a raw device. 
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cg4dd 

The Sun-3/1 10 color display used as a raw device. 
pixwindd 

A monochrome (one bit deep) graphics window within the Suntools 
window environment. This window may appear on either a color or 
monochrome display. 

cgpixwindd 

A color graphics window within the Suntools window environment. 
This window must appear on a color display. 

gpldd 

A Sun-2/160 or Sun-3/ 160 graphics display with a Graphics Processor 
option. 

gplpixwindd 

A color graphics window within the Suntools window environment run- 
ning on a Sun-2/160 or Sun-3/ 160 color graphics display with a Graph- 
ics Processor option. 

Only view surface types cgldd, cg2dd, cg4dd, cgpixwindd, gpldd, and 
gplpixwindd support hidden surface removal. In the discussion above, gray 
scale devices are considered to be color devices. 

As shown above, all required pointer manipulation can be done with the 
FORTRAN loc library subroutines, which returns the address of its argu- 
ment as an integer. 

SunCore function arguments which are pointers to structures can be declared 
as arrays in FORTRAN. For example, the C and FORTRAN declarations of 
the SunCore raster structure are shown below; 



C Code 


FORTRAN Code 


struct { 


integer raster ( 4 ) 


int width, height, depth; 




short *bits; 




} raster; 





Then the following fragments of C and FORTRAN code are equivalent: 



C Code 


FORTRAN Code 


short data [16]; 


integer*2 


data (16) 


raster. width = 16; 


raster (1) 


= 16 


raster . height = 16; 


raster (2) 


= 16 


raster. depth = 1; 


raster (3) 


= 1 


raster. bits = data; 


raster ( 4 ) 


= loc (data) 



□ Some SunCore structures contain both andint’s float’s. For instance, the 
argument to inquire_viewing_parameter s ( ) contains both int’s and 
float’s. This can be handled in FORTRAN by declaring a REAL array and 
an INTEGER array which are made to share storage by an EQUIVALENCE 
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Statement. Then following die call to the inquiry function, the REAL com- 
ponents can be accessed by using the REAL array and the INTEGER com- 
ponents accessed via the INTEGER array. 

□ Since FORTRAN does not distinguish between upper-case and lower-case 
letters in identifiers, any FORTRAN program unit which includes the 
usercore77 . h header file cannot use identifiers with the same spelling as 
any constant defined in that header file (regardless of case). 

□ The filetoraster and rastertofile functions inC take an argument 
that is a UNDCt file descriptor. The corresponding argument to the FORTRAN 
functions is a logical unit number (LUN). This unit should be explicitly 
opened by using the FORTRAN open statement. I/O to the opened file should 
be done only via the filetoraster and rastertofile functions. 

D.2. Example Program This example is the FORTRAN equivalent of the very simple program for draw- 

ing a martini glass. 



include "/usr/include/f77/usercore77 .h" 

integer vsurf (VWSURFSIZE) 
integer pixwindd 
external pixwindd 

integer InitializeCore, InitializeVwsurf , SelectVwsurf 
real glassdx(9), glassdyO) 

data glassdx /-lO . 0, 9 . 0, 0 . 0, -14 . 0, 30 . 0, -14 . 0, 0 . 0, 9 . 0 , -10 . 0/ 
data glassdy /O . 0, 1 . 0, 19 . 0, 15 . 0, 0 . 0, -15 . 0, -19 . 0, -1 . 0, 0.0/ 
data vsurf /VWSURFSIZE*0/ 

vsurf (DDINDEX) = loc (pixwindd) 

if (InitializeCore (BASIC, NOINPUT, TWOD) .ne. 0) call exit(l) 

if (InitializeVwsurf (vsurf , FALSE) .ne. 0) call exit (2) 

if (SelectVwsurf (vsurf ) .ne. 0) call exit (3) 

call SetViewport2 (0 . 125, 0.875, 0.125, 0.75) 

call SetWindow (-50 . 0, 50.0, -10.0, 80.0) 

call CreateTempSeg ( ) 

call MoveAbs2 (0 . 0, 0.0) 

call PolylineRel2 (glassdx, glassdy, 9) 

call MoveRel2 (-12 . 0, 33.0) 

call LineRel2 (24 . 0, 0.0) 

call CloseTempSeg 0 

call sleep (10) 

call DeselectVwsurf (vsurf ) 

call TerminateCore ( ) 

end 

V _> 



Figure D- 1 FORTRAN Example Program 



t UNIX is a registered trademark of AT&T. 




Revision A, of 9 May 1988 







Appendix D — Using SunCore with Fortran-77 Programs 155 



D.3. Correspondence 

Between C Names and 
FORTRAN Names 



Table D-2 Correspondence Between C Names and FORTRAN Names 



C Name 


FORTRAN Name 


allocate_raster 


allocateraster 


await_any_button 


await anybutton 


await any button get locator 2 


awtbuttongetloc2 


await any button get_valuator 


awtbutt onget val 


await_keyboard 


await keyboard 


await_pick 


awaitpick 


await stroke 2 


await St roke2 


begin_batch_of_updates 


beginbatchupdate 


close_retained_segment 


closeretainseg 


close temporary segment 


closetempseg 


create_retained_segment 


creator etainseg 


create_temporary_segment 


createtempseg 


define color indices 


def color indices 


delete all retained segments 


delallretainsegs 


delete_retained_segment 


delretainsegment 


deselect_view_surf ace 


deselectvwsurf 


end_batch_of_updates 


endbatchupdate 


f ile_to_raster 


filet or aster 


free_raster 


f reeraster 


ge t_mou s e_s t a t e 


getmousestate 


get_raster 


getraster 


initialize core 


initializecore 


initialize device 


initial izedevice 


initialize view surface 


initializevwsurf 


inquire charjust 


inqchar just 


inquire charpath 2 


inqcharpath2 


inquire charpath 3 


inqcharpath3 


inquire charprecision 


inqcharprecision 


inquire charsize 


inqcharsize 


inquire charspace 


inqchar space 


inquire_charup_2 


inqcharup2 


inquire_charup_3 


inqcharup3 


inquire color_indices 


inqcolor indices 


inquire current position 2 


inqcurrpos2 


inquire current position 3 


inqcurrpos3 


inquire detectability 


inqdetect ability 


inquire echo 


inqecho 


inquire echo^position 


inqechoposition 


inquire_echo surface 


inqecho surface 


inquire fill index 


inqf illindex 


inquire font 


inqfont 


inquire highlighting 


inqhighlighting 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 



C Name 


FORTRANName 


inquire_image_trans format ion_2 


inqimgtransform2 


inquire image transformation_3 


inqimgtransform3 


inquire image trans format ion_type 


inqimgxformtype 


inquire_image_translate_2 


inqimgtranslate2 


inquire_image_translate_3 


inqimgtranslate3 


inquire_inverse_composite_matrix 


inqinvcompmatrix 


inquire keyboard 


inqkeyboard 


inquire line_index 


inqlineindex 


inquire_line style 


inqlinestyle 


inquire linewidth 


inqline width 


inquire_locator_2 


inqlocator2 


inquire_marker_symbol 


inqmarker symbol 


i n qu i r e_n dc_spa c e_2 


inqndcspace2 


inquire_ndc_space_3 


inqndcspace3 


i n qu i r e_ope n_r e t a i n ed_s e gitie nt 


inqopenretainseg 


i nqu ir e_ope n_t empor ar y_s egmen t 


inqopentempseg 


inquire^pen 


inqpen 


inquire j>ick_id 


inqpickid 


inquire_polygon_edge_style 


inqpolyedgestyle 


inquire_polygon_interior_style 


inqpolyintr style 


inquire_primitive_attributes 


inqprimattribs 


inquire_j5ro jection 


inqpro jection 


inquire_rasterop 


inqrasterop 


inquire_retained_segment_names 


inqretainsegname 


inquire_retained_segment_surf aces 


inqretainsegsurf 


inquire segment_detectability 


inqsegdetectable 


inquire segment highlighting 


inqseghighlight 


inquire segment image transformation 2 


inqsegimgxf orm2 


inquire_segment_image_transformation_3 


inqsegimgxf orm3 


inquire segment_image transformation_type 


inqsegimgxf rmtyp 


inquire_segment_image_translate_2 


inqsegimgxlate2 


inquire segment image translate 3 


inqsegimgxlate3 


inquire segment_visibility 


inqsegvisibility 


inquire stroke 


inqstroke 


i n qu i r e_t ex t_e X t e n t_2 


inqt ext extent 2 


inquire_text_extent_3 


inqtext extent 3 


inquire_text_index 


inqtextindex 


inquire valuator 


inqvaluator 


inc[uire view depth 


i nqvi e wdept h 


inquire viewj)lane distance 


inqviewplanedist 


inquire view_jplane normal 


inqviewplanenorm 


inquire view ref erence_point 


inqviewref point 


inquire view up 2 


inqviewup2 


inquire view up 3 


inqviewup3 


inquire viewing control_parameters 


inqvwgcntrlparms 


inquire viewing parameters 


inqviewingparams 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 



C Name 


FORTRAN Name 


inquire_viewport_2 


inqviewport 2 


inquire viewport 3 


inqviewport 3 


inquire visibility 


inqvisibility 


inquire_window 


inqwindow 


inquire_world coordinate_matrix_2 


inqworldmatrix2 


inquire world coordinate_matrix 3 


inqworldmatrix3 


line abs 2 


lineabs2 


line abs 3 


lineabs3 


line rel 2 


linerel2 


line rel_3 


linerel3 


map ndc to world 2 


mapndctoworld2 


map_ndc_t o_wor ld_3 


mapndctoworld3 


map world to ndc 2 


mapworldtondc2 


map_wo r 1 d_t o_n dc_3 


mapworldtondc3 


marker abs 2 


markerabs2 


mar ker_ab s_3 


markerabs3 


marker rel 2 


markerrel2 


marker rel 3 


markerrel3 


move abs 2 


moveabs2 


move_ab s_3 


moveabs3 


move_rel 2 


moverel2 


move rel 3 


moverel3 


new frame 


newf rame 


polygon_abs_2 


polygonabs2 


polygon_abs_3 


polygonabs3 


polygon rel 2 


polygonrel2 


polygon_rel 3 


polygonrel3 


polyline abs 2 


polylineabs2 


polyline_abs_3 


polylineabs3 


polyline_rel 2 


polylinerel2 


polyline rel 3 


polylinerel3 


polymarker_abs 2 


polymarkerabs2 


polymarker abs 3 


polymarker abs 3 


polymarker_rel 2 


polymarkerrel2 


polymarker rel 3 


polymarkerrel3 


print error 


printerror 


put_raster 


putraster 


raster_to file 


rastertof ile 


rename retained segment 


renameretainseg 


report_most recent error 


reportrecenterr 


restore segment 


restore segment 


save segment 


savesegment 


select view surface 


selectvwsurf 


set_back plane clipping 


setbackclip 


set_char just 


setchar just 


set_charpath 2 


setcharpath2 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 



C Name 




FORTRANName 


set_charpath_3 




setcharpath3 


set_charprecision 




setcharprecision 


set_charsize 




setcharsize 


set_char space 




set char space 


set_charup_2 




setcharup2 


set_charup_3 




setcharup3 


set coordinate system type 




setcoordsystype 


set_detectability 




set detectability 


set_drag 




setdrag 


set_echo 




setecho 


set_echo_group 




setechogroup 


set_echo_position 




setechoposition 


set_echo surface 




set echo surf ace 


set_fill index 




setf illindex 


set font 




setfont 


s e t_f r o nt_j) 1 an e_c lipping 




setfrontclip 


set_highlighting 




sethighlighting 


set image transf ormation_2 




setimgtransform2 


s e t_ima ge_t r an s f o r ma t i o n_3 




setimgtransform3 


set_image transformation type 


setimgxformtype 


s e t_ima ge_t r an s 1 a t e_2 




setimgtranslate2 


set_image translate 3 




setimgtranslate3 


s et_keyboar d 




setkeyboard 


set_light direction 




setlightdirect 


set_line_index 




setlineindex 


set_linestyle 




setlinestyle 


set_linewidth 




setlinewidth 


set_locator_2 




setlocator2 


s e t_mar ke r_s ymbo 1 




setmarker symbol 


set_ndc space_2 




setndcspace2 


set_ndc space 3 




setndcspace3 


set_output clipping 




set output clip 


set_pen 




setpen 


set_pick 




setpick 


set_pick_id 




setpickid 


set_polygon_edge_style 




setpolyedgestyle 


set_polygon_interior style 




setpolyintr style 


set_primitive attributes 




setprimattribs 


s et_pr o j e c t ion 




setpro jection 


set_rasterop 




setrasterop 


set_segment detectability 




setsegdetectable 


set_segment highlighting 




set seghighlight 


set_segment_image_transf ormation 2 


setsegimgxform2 


set_segment_image_transf ormation 3 


setsegimgxform3 


set_segment_image translate 


2 


setsegimgxlate2 


set_segment_image_translate_ 


3 


setsegimgxlate3 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 



C Name 


FORTRAN Name 


set segment visibility 


setsegvisibility 


set_shading_j)arameters 


setshadingparams 


set_stroke 


setstroke 


set text index 


settextindex 


set_valuator 


setvaluator 


set_vertex indices 


set vert exindices 


set_vertex normals 


set vert exnormals 


set_view_depth 


setviewdepth 


set view_j)lane distance 


setviewplanedist 


set view plane normal 


setviewplanenorm 


set view ref erence_point 


set viewref point 


set_viewport_2 


set viewport 2 


set_viewport_3 


setviewport3 


set_view_up_2 


setviewup2 


set_view_up_3 


setviewup3 


set viewing _parameters 


setviewingparams 


set visibility 


set visibility 


set window 


setwindow 


set window clipping 


setwindowclip 


set world coordinate matrix 2 


setworldmatrix2 


set world coordinate matrix 3 


setworldmatrix3 


set_zbuf f er_cut 


setzbuf f ercut 


size_r aster 


sizeraster 


terminate_core 


terminatecore 


terminate_device 


terminatedevice 


terminate view surface 


terminatevwsurf 


text 


text 



D.4. FORTRAN Interfaces Note: Although all SunCore procedures are declared here as functions, each may 

to SunCore also be called as a subroutine if the user does not want to check the returned 

value. 

integer function allocateraster (raster) 
integer raster (4) 



integer function awaitanybutton (time, buttonnum) 
integer time, buttonnum 



integer function awtbuttongetloc2 (time, locatornum, buttonnum, x, y) 
integer time, locatornum, buttonnum 
real x, y 



integer function awtbuttongetval (time, valuatornum, buttonnum, value) 
integer time, valuatornum, buttonnum 
real value 



integer function 



await keyboard (time. 



keyboardnum. 



inputstring, length) 
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integer time, keyboardnum 
character* ( *) inputstring 
integer length 

integer function awaitpick (time, picknum, segname, pickid) 
integer time, picknum, segname, pickid 

integer function awaitstroke2 (time, strokenum, arraysize, xarray, yarray, n) 
integer time, strokenum, arraysize 
real xarray, yarray 
integer n 

integer function beginbatchupdate () 

integer function closeretainseg ( ) 

integer function closetempseg ( ) 

integer function createretainseg (segname) 
integer segname 

integer function createtempseg ( ) 

integer function defcolorindices (surfacename, il, i2, red, green, blue) 
integer surfacename (*) 
integer il, i2 

real red(*), green (*), blue(*) 

integer function delallretainsegs ( ) 

integer function delretainsegment (segname) 
integer segname 

integer function deselectvwsurf (surfacename) 
integer surfacename (*) 

integer function endbatchupdate ( ) 

integer function f iletoraster (rasf id, raster, map) 
integer rasfid 
integer raster ( 4 ) 
integer map (3) 

integer function freeraster (raster) 
integer raster ( 4 ) 

integer function getmousestate (devclass, devnum, x, y, buttons) 
integer devclass, devnum 
real x, y 
integer buttons 

integer function getraster (surfacename, xmin, xmax, ymin, ymax, xd, yd, raster) 
integer surfacename (*) 
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real xmin, xmax, ymin, ymax 
integer xd, yd 
integer raster ( 4 ) 

integer function initializecore (outputlevel, inputlevel, dimension) 
integer output level, input level, dimension 

integer function initializedevice (deviceclass, devicenum) 
integer deviceclass, devicenum 

integer function initializevwsurf (surf acename, type) 
integer surfacename (*) 
integer type 

integer function inqchar just ( just ) 
integer just 

integer function inqcharpath2 (dx, dy) 
real dx, dy 

integer function inqcharpathS (dx, dy, dz) 
real dx, dy, dz 

integer function inqcharprecision (charprecision) 
integer charprecision 

integer function inqcharsize (charwidth, charheight) 
real charwidth, charheight 

integer function inqcharspace (charspace) 
real charspace 

integer function inqcharup2 (dx, dy) 
real dx, dy 

integer function inqcharupS (dx, dy, dz) 
real dx, dy, dz 

integer function inqcolorindices (surfacename, il, i2, red, green, blue) 
integer surfacename ( *) 
integer il, i2 

real red(*), green (*), blue(*) 

integer function inqcurrpos2 (x, y) 
real x, y 

integer function inqcurrpos3 (x, y, z) 
real x, y, z 

integer function inqdetectability (detectability) 
integer detectability 

integer function inqecho (deviceclass, devicenum, echotype) 
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integer deviceclass, devicenum, echotype 

integer function inqechoposition (deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 

integer function inqechosurface (deviceclass, devicenum, surfacename) 
integer deviceclass, devicenum 
integer surfacename (*) 

integer function inqfillindex (index) 
integer index 

integer function inqfont (font) 
integer font 

integer function inqhighlighting (highlighting) 
integer highlighting 

integer function inqimgtransform2 (sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 

integer function inqimgtransformS (sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqimgxf ormtype (type) 
integer type 

integer function inqimgtranslate2 (tx, ty) 
real tx, ty 

integer function inqimgtranslateS (tx, ty, tz) 
real tx, ty, tz 

integer function inqinvcompmatrix (array) 
real array (4, 4) 

integer function inqkeyboard (keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character* ( *) initstring 
integer initcursor 

integer function inqlineindex (index) 
integer index 

integer function inqlinestyle (linestyle) 
integer linestyle 

integer function inqlinewidth (linewidth) 
real linewidth 

integer function inqlocator2 (locatornum, x, y) 
integer locatornum 
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real x, y 

integer function inqmarkersymbol (symbol) 
integer symbol 

integer function inqndcspace2 (width, height) 
real width, height 

integer function inqndcspaceS (width, height, depth) 
real width, height, depth 

integer function inqopenretainseg (segname) 
integer segname 

integer function inqopentempseg (open) 
integer open 

integer function inqpen (pen) 
integer pen 

integer function inqpickid (pickid) 
integer pickid 

integer function inqpolyedgestyle (style) 
integer style 

integer function inqpolyintrstyle (style) 
integer style 

integer function inqprimattribs (primattr) 
integer primattr (28) 

Note: The actual argument in the calling program corresponding to primattr should be an array which can be refer- 
enced both as a real array and as an integer array in order to access both integer valued and real valued primitive attri- 
butes. This can be done using the equivalence statement. 

integer function inqpro jection (pro jection, dxproj, dyproj, dzproj) 
integer projection real dxproj, dyproj, dzproj 

integer function inqrasterop (rop) 
integer rop 

integer function inqretainsegname (arraysize, namearray, numberof segments) 
integer arraysize, namearray (*) , numberof segments 

integer function inqretainsegsurf (segname, arraysize, vwsurfarray, numsurf) 
integer segname, arraysize 
integer vwsurfarray (*) 
integer numsurf 

Note: arraysize should give the number of view surface structures which can be held in vwsurfarray. Each structure 
requires VWSURFSIZE elements of vwsurfarray. 

integer function inqsegdetect able (segname, detectability) 
integer segname, detectability 
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integer function inqseghighlight (segname, highlighting) 
integer segname, highlighting 

integer function inqsegimgxform2 (segname, sx, sy, a, tx, ty) 

integer segname 

real sx, sy, a, tx, ty 

integer function inqsegimgxformS (segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqsegimgxfrmtyp (segname, type) 
integer segname, type 

integer function inqsegimgxlate2 (segname, tx, ty) 
integer segname 
real tx, ty 

integer function inqsegimgxlateS (segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function inqsegvisibility (segname, visibility) 
integer segname, visibility 

integer function inqstroke (strokenum, bufsize, dist, time) 
integer strokenum, bufsize 
real dist 
integer time 

integer function inqtextextent2 (string, dx, dy) 
character* (*) string 
real dx, dy 

integer function inqtextextent3 (string, dx, dy, dz) 
character* (*) string 
real dx, dy, dz 

integer function inqtext index (index) 
integer index 

integer function inqvaluator (valuatornum, initialvalue, low, high) 

integer valuatornum 

real initialvalue, low, high 

integer function inqviewdepth (f rontdistance, backdistance) 
real f rontdistance, backdistance 

integer function inqviewplanedist (viewdistance) 
real viewdistance 

integer function inqviewplanenorm (dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 
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integer function inqviewrefpoint (x, y, z) 
real x, y, z 

integer function inqviewup2 (dxup, dyup) 
real dxup, dyup 

integer function inqviewupS (dxup, dyup, dzup) 
real dxup, dyup, dzup 

integer function inqvwgcntrlparms (windowclip, frontclip, backclip, type) 
integer windowclip, frontclip, backclip, type 

integer function inqviewingparams (viewparams) 
real viewparams (26) 

Note: The actual argument in the calling program corresponding to viewparams should be an array which can be 
referenced both as a real array and as an integer array in order to access both integer valued and real valued viewing 
parameters. This can be done using the equivalence statement. 

integer function inqviewport2 (xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function inqviewportS (xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function inqvisibility (visibility) 
integer visibility 

integer function inqwindow (umin, umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function inqworldmatrix2 (array) 
real array (3, 3) 

integer function inqworldmatrix3 (array) 
real array (4, 4) 

integer function lineabs2 (x, y) 
real x, y 

integer function lineabs3 (x, y, z) 
real x, y, z 

integer function linerel2 (dx, dy) 
real dx, dy 

integer function linerel3 (dx, dy, dz) 
real dx, dy, dz 

integer function mapndctoworld2 (ndcx, ndcy, wldx, wldy) 
real ndcx, ndcy, wldx, wldy 

integer function mapndctoworld3 (ndcx, ndcy, ndcz, wldx, wldy, wldz) 
real ndcx, ndcy, ndcz, wldx, wldy, wldz 
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integer function mapworldtondc2 (wldx, wldy, ndcx, ndcy) 
real wldx, wldy, ndcx, ndcy 

integer function mapworldtondc3 (wldx, wldy, wldz, ndcx, ndcy, ndcz) 
real wldx, wldy, wldz, ndcx, ndcy, ndcz 

integer function markerabs2 (x, y) 
real x, y 

integer function markerabsS (x, y, z) 
real x, y, z 

integer function markerrel2 (dx, dy) 
real dx, dy 

integer function markerrelS (dx, dy, dz) 
real dx, dy, dz 

integer function moveabs2 (x, y) 
real x, y 

integer function moveabs3 (x, y, z) 
real x, y, z 



integer function moverel2 (dx, dy) 
real dx, dy 

integer function moverel3 (dx, dy, dz) 
real dx, dy, dz 

integer function newframeO 

integer function polygonabs2 (xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 



integer function polygonabs3 (xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray(*) 
integer n 



integer function polygonrel2 (dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 

integer function polygonrel3 (dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function polylineabs2 (xarray, yarray, n) 
real xarray (*), yarray (*) 
integer n 

integer function polylineabs3 (xarray, yarray, zarray, n) 
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real xarray(*), yarray(*), zarray(*) 
integer n 

integer function polylinerel2 (dxarray, dyarray, n) 
real dxarray (*), dyarray(*) 
integer n 

integer function polylinerel3 (dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function polymarkerabs2 (xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 

integer function polymarkerabsS (xarray, yarray, zarray, n) 
real xarray (*), yarray(*), zarray(*) 
integer n 

integer function polymarkerrel2 (dxarray, dyarray, n) 
real dxarray (*), dyarray (*) 
integer n 

integer function polymarkerrelS (dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function printerror (message, errornum) 
character* ( *) message 
integer errornum 

integer function put raster (raster) 
integer raster (4) 

integer function rastertofile (raster, map, rasfid, n) 
integer raster (4) 
integer map (3) 
integer rasfid, n 

integer function renameretainseg (segname, newname) 
integer segname, newname 

integer function reportrecenterr (errornum) 
integer errornum 

integer function restoresegment (segname, filename) 
integer segname 
character* ( *) filename 

integer function savesegment (segname, filename) 
integer segname 
character* ( *) filename 
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integer function selectvwsurf (surf acename) 
integer surf acename (*) 

integer function setbackclip (onof f ) 
integer onoff 

integer function setchar just ( just) 
integer just 

integer function setcharpath2 (dx, dy) 
real dx, dy 

integer function setcharpathS (dx, dy, dz) 
real dx, dy, dz 

integer function setcharprecision (charprecision) 
integer charprecision 

integer function setcharsize (charwidth, charheight) 
real charwidth, charheight 

integer function setcharspace (charspace) 
real charspace 

integer function setcharup2 (dx, dy) 
real dx, dy 

integer function setcharupS (dx, dy, dz) 
real dx, dy, dz 

integer function setcoordsystype (type) 
integer type 

integer function setdetectability (detectability) 
integer detectability 

integer function setdrag (mode) 
integer mode 

integer function setecho (deviceclass, devicenum, echotype) 
integer deviceclass, devicenum, echotype 

integer function setechogroup (deviceclass, devicenumarray, n, echotype) 
integer deviceclass, devicenumarray (*) , n, echotype 

integer function setechoposition (deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 

integer function setechosurface (deviceclass, devicenum, surfacename) 
integer deviceclass, devicenum 
integer surfacename (*) 
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integer function setfillindex (index) 
integer index 

integer function setfont (font) 
integer font 

integer function setf rontclip (onof f ) 
integer onoff 

integer function sethighlighting (highlighting) 
integer highlighting 

integer function setimgtransform2 (sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 

integer function setimgtransformS (sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setimgxf ormtype (type) 
integer type 

integer function setimgtranslate2 (tx, ty) 
real tx, ty 

integer function setimgtranslateS (tx, ty, tz) 
real tx, ty, tz 

integer function setkeyboard (keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character* (*) initstring 
integer initcursor 

integer function setlightdirect (dx, dy, dz) 
real dx, dy, dz 

integer function set lineindex (index) 
integer index 

integer function setlinestyle (linestyle) 
integer linestyle 

integer function setlinewidth (linewidth) 
real linewidth 

integer function setlocator2 (locatornum, x, y) 
integer locatornum 
real x, y 

integer function setmarkersymbol (symbol) 
integer symbol 

integer function setndcspace2 (width, height) 
real width, height 
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integer function setndcspaceS (width, height, depth) 
real width, height, depth 

integer function setoutputclip (onof f ) 
integer onoff 

integer function setpen(pen) 
integer pen 

integer function setpick (picknum, aperture) 
integer picknum 
real aperture 

integer function setpickid(pickid) 
integer pickid 

integer function setpolyedgestyle (style) 
integer style 

integer function setpolyintrstyle (style) 
integer style 

integer function setprimattribs (primattr) 
integer primattr (2 8) 

Note: The actual argument in the calling program corresponding to primattr should be an array which can be refer- 
enced both as a real array and as an integer array in order to access both integer valued and real valued primitive attri- 
butes. This can be done using the equivalence statement. 

integer function setpro jection (pro jection, dxproj, dyproj, dzproj) 

integer projection 

real dxproj, dyproj, dzproj 

integer function setrasterop (rop) 
integer rop 

integer function setsegdetectable (segname, detectability) 
integer segname, detectability 

integer function set seghighlight (segname, highlighting) 
integer segname, highlighting 

integer function setsegimgxform2 (segname, sx, sy, a, tx, ty) 

integer segname 

real sx, sy, a, tx, ty 

integer function setsegimgxformS (segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setsegimgxlate2 (segname, tx, ty) 
integer segname 
real tx, ty 
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integer function setsegimgxlateS (segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function setsegvisibility (segname, visibility) 
integer segname, visibility 

integer function setshadingparams (ambient, diffuse, specular, flood, bump, hue, style) 
real ambient, diffuse, specular, flood, bump 
integer hue, style 

integer function setstroke (strokenum, buffersize, distance, time) 
integer strokenum, buffersize 
real distance 
integer time 

integer function settext index (index) 
integer index 

integer function setvaluator (valuatornum, initialvalue, low, high) 

integer valuatornum 

real initialvalue, low, high 

integer function setvertexindices (colorindexlist , n) 
integer colorindexlist (*) , n 

integer function setvertexnormals (xlist, ylist, zlist, n) 
real xlist (*), ylist (*), zlist (*) 
integer n 

integer function setviewdepth (f rontdistance, backdistance) 
real f rontdistance, backdistance 

integer function setviewplanedist (distance) 
real distance 

integer function setviewplanenorm (dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 

integer function setviewport2 (xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function setviewportS (xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function setviewrefpoint (x, y, z) 
real x, y, z 

integer function setviewup2 (dx, dy) 
real dx, dy 

integer function setviewupS (dx, dy, dz) 
real dx, dy, dz 
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integer function setviewingparams (viewparams) 
real viewparams (26) 

Note: The actual argument in the calling program corresponding to viewparams should be an array which can be 
referenced both as a real array and as an integer array in order to access both integer valued and real valued viewing 
parameters. This can be done using the equivalence statement 

integer function setvisibility (visibility) 
integer visibility 

integer function setwindow (umin, Umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function setwindowclip (onof f ) 
integer onoff 

integer function setworldmatrix2 (array) 
real array (3, 3) 

integer function setworldmatrix3 (array) 
real array (4, 4) 

integer function setzbuf fercut (surfacename, xlist, zlist, n) 
integer surfacename (*) 
real xlist (*), zlist (*) 
integer n 

integer function sizeraster (surfacename, xmin, xmax, ymin, ymax, raster) 

integer surfacename ( *) 

real xmin, xmax, ymin, ymax 

integer raster (4) 

integer function terminatecore () 

integer function terminatedevice (deviceclass, devicenum) 
integer deviceclass, devicenum 

integer function terminatevwsurf (surfacename) 
integer surf acename ( *) 

integer function text (string) 
character* (*) string 
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Using SunCore with Pascal Programs 



All functions provided in SunCore may be called from Pascal programs by link- 
ing them with the /usr/lib/libcorepas . a library by using the Pascal 
compiler with a command line of the form: 



% pc -f switch -o grab grab.p -Icorepas -Icore -Isunwindow -Ipixrect -liti 
< > 



where grab.p is the Pascal source program. The -f switch option will cause 
the compiler to take advantage of floating point hardware if it is available. Oth- 
erwise, the compiler will emulate this floating point support with software. (For 
more information on floating point options, see Appendix F). Note that 
/usr/lib/libcore . a must be linked with the program (the -Icore 
option), and /usr/lib/libcorepas . a must come before it (the —Icore- 
pas option). 

E.l. Programming The files typedef spas . h, usercorepas . h, devincpas .h and 

Requirements sunpas . h from the /usr /include/pascal directory must be included in 

the user’s source code to provide the necessary declarations for the Pascal inter- 
face to SunCore. Pascal programs which call SunCore functions must place 
these include files in the most global declaration section of the program: 

program example (input, output ) 

tinclude ’ /usr/include/pascal/usercorepas . h' 

#include ’ /usr/include/pascal/typedef spas . h' 

var 

{user declarations} 

#include ' /usr/ include/pascal/devincpas . h' 
tinclude ' /usr/ include/pascal/sunpas .h' 

If the Pascal program is composed of separately compiled files, these include 
statements must be in each Pascal file which uses SunCore functions and the 
corresponding defined constants. Defined constants for SunCore (see section on 
Useful Constants in the introduction to this manual) are set in the file 
/usr/include/pascal/usercorepas .h. The default primitive attri- 
bute stmcture PRIMATTS provided inusercore.h and described in the section 
describing set _primitive attributes is not provided inusercorepas.h. 
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The Sun release of Pascal does not support the passing of variable length arrays 
as arguments in function or procedure calls. Therefore, fixed length arrays which 
are compatible with the Sw/iCore-Pascal interface are declared as predefined 
types in the typedef spas . h file (see the Declarations section of this appen- 
dix). The length of these arrays in 256. The length of character strings passed 
from Pascal programs to SunCore must also be 256 characters. 

The correspondence between the full SunCore names and the Pascal names 
appears in the Function Declarations section of this appendix. To provide a 
mechanism for returning the status of calls to SunCore routines, all SunCore rou- 
tines must be called as functions from Pascal. Finally, although most SunCore 
functions use floats (32-bit reals), Pascal uses 64-bit reals. However, the Pascal 
programmer is only required to provide reals. SunCore functions which have 
structures as their arguments have corresponding predefined types in Pascal (see 
the Type Declarations section of this appendix). 

Routines Using View Surface View surface names in SunCore are structures containing pointers to device 

Names driver routines. The device driver names are supplied by the include file 

devincpas . h. The user may then simply use one of the names listed in Table 
E-1: 

Table E-1 Viewsurface Types 



Symbol 


Description 


bwldd 


Sun-1 monochrome display 


bw2dd 


Sun-2 monochrome display 


cgldd 


Sun-1 color display 


cg2dd 


Sun-2 color display 


cg4dd 


Sun-3/ 110 color display 


gpldd 


Graphics Processor 


pixwindd 


windows on the Sun-1 monochrome display 


cgpixwindd 


windows on a color display 


gplpixwindd 


windows with the Graphics Processor 



The pasloc function (provided in the 5unC<?re-Pascal interface) transforms the 
function corresponding to the device driver into an integer which can then be 
inserted in the appropriate place in the device driver structure (see following 
example). 
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Table E-2 Comparison of C and Pascal Statements 



C Code 


Pascal Code 


struct vwsurf dsurf = NULL VWSURF; 


var 


int bwlddO; 


dsurf : vwsurf; 


• 


tstr : vwsurf st; 


• 


tstr : = ' ' ; 


dsurf. dd = bwldd; 


dsurf. dd := pasloc (bwldd) ; 
dsurf . screenname := tstr; 
dsurf . windowname := tstr; 
dsurf . windowfd := 0; 
dsurf . instance := 0; 
dsurf . cmapsize := 0; 
dsurf . cmapname := tstr; 
dsurf. flags := 0; 
dsurf .ptr := 0; 


initialize view surf ace (Sdsurf, FALSE); 


X := InitializeVwsurf (dsurf , FALSE); 



Assigning a literal string of two spaces (blanks) to the tstr variable will initialize 
the character array to all spaces. 



Routines Using Rasters and For uses of SunCore functions which have rasters or colormaps as arguments 

Colormaps which do not involve arithmetic direct manipulation by the programmer (for 

example, writing a raster to a file), the following restrictions on the functions do 
not apply and the programmer is only required to call the function. SunCore ras- 
ter and colormap stmctures contain pointers to variable length data (that is, 
dynamic arrays). The SunCore-Pd&cdX interface declares these varaibles as 
integers. 

Pascal programmers wishing to alter the contents of the colormap or raster data 
within a program can write a C function which uses the pointer value returned in 
Pascal to copy the information into a fixed-length array. Arithmetic operations 
can then be performed on the data using conventional Pascal statements. The 
programmer can then write another C function to copy the information back into 
the array pointed to by the pointer returned by the SunCore-Pd&cdX interface. 
These C functions are not provided because the size of the fixed-length array will 
vary greatiy among different applications. Therefore, the individual Pascal pro- 
grammer must decide how large an array to declare for each application. 

E.2. Example Program The use of the SunCore-P^&c^X interface is illustrated by showing the text of a 

program for drawing the martini glass used in previous tutorial examples. 

Figure E- 1 Pascal Example Program 

, ^ 

program martiniglass (input , output ) ; 

tinclude ' /usr/ include/pascal/usercorepas .h' ; 
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#include ' /usr/include/pascal/typedef spas .h' ; 



glassdx, glassdy: parr {type parr is an array of reals of 
length 256 declared in typedefs.h}; 

x: integer ; 
dsurf :vwsurf ; 
tstr rvsurfst; 

function sleep (x: integer) : integer; external; 
tinclude ' /usr/include/pascal/sunpas .h' ; 

#include ' /usr/include/pascal/devincpas .h' ; 



procedure loaddata; 
begin 

glassdx [1] 
glassdx [2] 
glassdx [3] 
glassdx [4] 
glassdx [5] 
glassdx [6] 
glassdx [7] 
glassdx [8] 
glassdx [9] 

end; 



- 10 . 0 ; 

9.0; 

0 . 0 ; 

-14.0; 

30.0; 

-14.0; 

0 . 0 ; 

9.0; 

- 10 . 0 ; 



glassdy [1] 
glassdy [2] 
glassdy [3] 
glassdy [4] 
glassdy [5] 
glassdy [6] 
glassdy [7] 
glassdy [8] 
glassdy [9] 



= 0 . 0 ; 

= 1 . 0 ; 

= 19.0; 

= 15.0; 

= 0.0; 

= -15.0; 
= -19.0; 
= -1.0; 

= 0 . 0 ; 



begin (main program} 

tstr := ' ' ; 

dsurf . screenname := tstr; 

dsurf .windowname := tstr; 

dsurf .windowfd := 0; 

dsurf. dd := pasloc (pixwindd) ; 

dsurf . instance := 0; 

dsurf . cmapsize := 0; 

dsurf . cmapname := tstr; 

dsurf. flags := 0; 

if (initializecore (BASIC, NOINPUT, TWOD) <> 0) then 

writeln (' error 1') 

else 

if (initializevwsurf (dsurf , FALSE) <> 0) then 
writeln {' error 2') 
else 

if (selectvwsurf (dsurf ) <> 0) then 
writeln (' error 3') 
else 

X := setviewport2 (0 . 125, 0.875, 0.125, 0.75); 

X := setwindow (-50 . 0, 50.0, -10.0, 80.0); 

X := createtempseg; 

X := moveabs2 (0 . 0, 0.0); 
loaddata; 

X := polylinerel2 (glassdx, glassdy, 9); 

X := moverel2 (-12 . 0, 33.0); 

X := linerel2 (24 . 0, 0.0); 

X := closetempseg; 
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E.3. Correspondence 

Between C Names and 
Pascal Names 



Table E-3 Correspondence Between C Names and Pascal Names 



C Name 


Pascal Name 


allocate raster 


allocater aster 


await_any_button 


await anybutton 


await any button get locator 2 


awtbuttongetloc2 


await any button_get_valuator 


awtbuttongetval 


await_keyboard 


await keyboard 


await_j5ick 


awaitpick 


await stroke_2 


await stroke2 


b e gi n_b at ch_o f _upda t e s 


beginbat chupdat e 


close_retained_segment 


closeretainseg 


close temporary segment 


closetempseg 


create_retained_segment 


createretainseg 


create_temporary_segment 


createtempseg 


define color indices 


def color indices 


delete_all_retained_segments 


delallretainsegs 


delete_retained_segment 


delretainsegment 


deselect view surface 


deselectvwsurf 


end_batch_of_updates 


e ndbat chupdat e 


file to raster 


f iletoraster 


f ree_raster 


f reeraster 


get_mouse_state 


getmousestate 


get raster 


getraster 


initialize core 


initializecore 


initialize device 


initializedevice 


initialize_view_surface 


initializevwsurf 


inquire_char just 


inqchar just 


inquire_charpath_2 


inqcharpath2 


inquire charpath 3 


inqcharpath3 


inquire charprecision 


inqcharprecision 


inquire charsize 


inqcharsize 


inquire charspace 


inqcharspace 


inquire_charup_2 


inqcharup2 


inquire charup_3 


inqcharup3 


inquire_color_indices 


inqco lor indices 


inquire current position_2 


inqcurrpos2 


inquire current_position 3 


inqcurrpos3 


inquire_detectability 


inqdetectability 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 



C Name 


Pascal Name 


inquire_echo 


inqecho 


inquire echo__position 


inqechoposition 


inquire echo surface 


inqechosurf ace 


inquire fill index 


inqf illindex 


inquire font 


inqfont 


inquire_highlighting 


inqhighlighting 


inquire image_trans formation 2 


inqimgtransform2 


inquire_image_trans format ion_3 


i nqimgt r an s f o rm3 


inquire image transformation type 


inqimgxformtype 


inquire_image_translate 2 


inqimgtranslate2 


inquire image translate 3 


i nqimgt ran slate 3 


inquire inverse composite matrix 


inqinvcompmatrix 


inquire keyboard 


inqkeyboard 


inquire line index 


inqlineindex 


inquire linestyle 


inqlinestyle 


inquire linewidth 


inqlinewidth 


inquire locator 2 


inqlocator2 


inquire_marker_symbol 


inqmarker symbol 


inquire ndc space 2 


inqndcspace2 


inquire_ndc_space_3 


inqndcspace3 


inquire_open_retained_segment 


inqopenretainseg 


inquire_open_temporary_segment 


inqopentempseg 


inquire_pen 


inqpen 


inquire_pick id 


inqpickid 


inquire_polygon_edge_style 


inqpolyedgestyle 


inquire_polygon_interior_style 


inqpolyintr style 


inquire_primitive attributes 


inqprimattribs 


inquire_pro jection 


inqpr ejection 


inquire_rasterop 


inqrasterop 


inquire_retained_segment names 


inqretainsegname 


inquire_retained_segment surfaces 


inqretainsegsurf 


inquire_segment_detect ability 


inqsegdetectable 


inquire_segment_highlighting 


inqseghighlight 


inquire_segment_image_trans formation 2 


inqsegimgxform2 


inquire_segment_image_trans format ion 3 


inqsegimgxf orm3 


inc[uire_segment_image_trans formation type 


inqsegimgxf rmtyp 


inquire_segment_image_translate_2 


inqsegimgxlate2 


inc[uire_segment_image translate 3 


inqsegimgxlate3 


inquire_segment_visibility 


inqsegvisibility 


inquire stroke 


inqstroke 


inquire_text extent 2 


inqtextextent2 


inquire text extent 3 


inqt ext extent 3 


inquire text index 


inqtextindex 


inquire valuator 


inqvaluator 


inquire view depth 


inqviewdepth 


inquire view_plane distance 


inqviewplanedist 






Revision A, of 9 May 1988 








Appendix E — Using SunCore with Pascal Programs 181 



Table E-3 Correspondence Between C Names and Pascal Names — Continued 



inquire view plane normal 


inqviewplanenorm 


inquire view ref erence_p>oint 


inqviewref point 


i n qu i r e_v ie w_up_2 


inqviewup2 


inquire view up 3 


inqviewup3 


inquire_viewing control_parameters 


inqvwgcntrlparms 


inquire_viewing_parameters 


inqviewingparams 


inquire_viewport_2 


inqviewport2 


inquire_viewport_3 


inqviewport 3 


inquire visibility 


inqvisibility 


inquire window 


inqwindow 


inquire world coordinate matrix_2 


inqworldmatrix2 


inquire world coordinate matrix_3 


inqworldmatrix3 


line abs 2 


lineabs2 


line abs 3 


lineabs3 


line rel 2 


linerel2 


line rel 3 


linerel3 


map ndc to world_2 


mapndctoworld2 


map_ndc to world_3 


mapndctoworld3 


map_world to ndc_2 


mapworldtondc2 


map_wo r 1 d_t o_n dc_3 


mapworldtondc3 


marker abs 2 


markerabs2 


marker abs 3 


marker abs 3 


marker_rel_2 


markerrel2 


marker_rel_3 


markerrel3 


move_abs_2 


moveabs2 


move_abs 3 


moveabs3 


move_rel_2 


mover el2 


move_rel_3 


moverel3 


new_f rame 


newframe 


polygon abs 2 


polygonabs2 


polygon_abs_3 


polygonabs3 


polygon_rel_2 


polygonrel2 


polygon_rel_3 


polygonrel3 


polyline_abs 2 


polylineabs2 


polyline_abs_3 


polylineabs3 


polyline_rel_2 


polylinerel2 


polyline rel 3 


polylinerel3 


polymarker abs 2 


polymarkerabs2 


polymarker_abs 3 


polymarkerabs3 


polymarker rel 2 


polymarkerrel2 


polymarker rel 3 


polymarkerrel3 


print error 


printerror 


put_raster 


putraster 


raster to file 


rastertof ile 


rename_retained segment 


renameretainseg 


report most recent error 


reportrecenterr 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 



C Name 


Pascal Name 


restore_segment 


restore segment 


save_segment 


savesegment 


select view surface 


selectvwsurf 


set back plane clipping 


setbackclip 


set_char just 


setchar just 


set_charpath_2 


setcharpath2 


set_charpath_3 


setcharpath3 


set charprecision 


set charprecision 


set charsize 


setcharsize 


set charspace 


setchar space 


set charup_2 


setcharup2 


set charup_3 


setcharup3 


set_coordinate_system_type 


setcoordsystype 


set_detectability 


setdetectability 


set_drag 


setdrag 


set echo 


setecho 


set_echo_group 


setechogroup 


set_echo_position 


setechoposition 


set echo surface 


setechosurface 


set fill index 


setf illindex 


set font 


setfont 


set_f ront_plane_clipping 


setfrontclip 


set highlighting 


sethighlighting 


s e t_ima ge_t r an s f o rma t i o n_2 


setimgtransform2 


set image transformation 3 


set imgt r a n s f o rm3 


s e t_ima ge_t r an s f o rmat i o n_t y pe 


setimgxformtype 


s e t_ima ge_t r an s 1 a t e_2 


set imgt ran slate 2 


set_image_translate_3 


set imgt ranslate3 


set_keyboard 


setkeyboard 


set light direction 


setlightdirect 


set_line_index 


setlineindex 


set linestyle 


setlinestyle 


set_linewidth 


setlinewidth 


set locator 2 


setlocator2 


s e t_mar ke r_s ymbo 1 


setmarker symbol 


set_ndc_space_2 


setndcspace2 


set_ndc_space_3 


setndcspace3 


set_output_clipping 


set output clip 


set_j?en 


setpen 


set_j>ick 


setpick 


set_pick_id 


setpickid 


set_polygon_edge_style 


setpolyedgestyle 


set polygon interior_style 


setpolyintr style 


set primitive_attributes 


setprimattribs 


set_pro jection 


setpro jection 


set_rasterop 


setrasterop 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 



C Name 


Pascal Name 


set segment detectability 


set segdetect able 


set segment highlighting 


set seghighlight 


set segment image transformation 2 


set segimgxf orm2 


set segment image t ran s format ion_3 


set segimgxf orm3 


s e t_s e gme n t _imag e_t r a n s 1 a t e_2 


setsegimgxlate2 


set segment_image_translate_3 


set segimgxlate3 


set segment visibility 


set segvisibility 


set shading parameters 


set shadingparams 


set stroke 


setstroke 


set text index 


settextindex 


set valuator 


setvaluator 


set vertex indices 


set vert exindices 


set vertex normals 


set vert exnormals 


set view depth 


setviewdepth 


set view plane distance 


setviewplanedist 


set view plane normal 


setviewplanenorm 


set view reference point 


setviewref point 


set view up 2 


setviewup2 


set view up 3 


setviewup3 


set viewing parameters 


setviewingparams 


set viewport 2 


setviewport2 


set_viewport_3 


set viewport 3 


set_visibility 


set visibility 


set_window 


setwindow 


set window clipping 


setwindowclip 


set world coordinate matrix 2 


setworldmatrix2 


set world_coordinate matrix 3 


setworldmatrix3 


set_zbuf f er_cut 


set zbuf fercut 


size raster 


sizeraster 


terminate core 


terminatecore 


terminate device 


terminatedevice 


terminate view surface 


terminatevwsurf 


text 


puttext 



E.4. Type Declarations The list on the following pages is a complete alphabetical list of the Pascal data 

structures in SunCore. 

type iarr = array [ 1 .. 256] of integer; 
type parr = array [1 . .256] of real; 
type cot = array [1 . .257] of char; 
type ivarray = array [1 . . 4, 1 . . 4] of real; 
type ivarrayl = array [1 . . 3, 1 . . 3] of real; 
type pttype = record 
X, y, z, w: real; 
end; 

type aspect = record 

width, height: real; 
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end; 

type primattr = record 

lineindx: integer; 
fillindx: integer; 
textindx: integer; 
linestyl: integer; 
polyintstyl: integer; 
polyedgstyl: integer; 
linwidth: real; 
pen: integer; 
font: integer; 
charsize: aspect; 

chrup, chrpath, chrspace: pttype; 
ch just : integer; 
chqualty: integer; 
marker: integer; 
pickid: integer; 
rasterop: integer; 
end; 

type rasttyp = record 

width: integer; 
height: integer; 
depth: integer; 
bits: integer; {var} 
end; 

type cmap = record 

typ: integer; 
nbyt : integer; 
dat : integer; {var} 
end; 

type windtype = record 

xmin, xmax, ymin, ymax:real; 

end; 

type porttype = record 

xmin, xmax, ymin,ymax, zmin, zmax: real; 

end; 

type vwprmtype = record 

vwrefpt: array [1..3] of real; 
vwplnorm: array [1..3] of real; 
viewdis : real ; 
f rontdis : real; 
backdis : real; 
pro jtype : integer; 
projdir: array [1..3] of real; 
window : windtype ; 
vwupdir: array [1..3] of real; 
viewport : porttype; 
end; 

type vwsurf = record 

screenname: array [1 . .DEVNAMESIZE] of char; 
windowname: array [1 . .DEVNAMESIZE] of char; 
windowf d : integer ; 
dd: integer; 
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instance : integer; 
cmapsize : integer ; 

cmapname: array [1 . .DEVNAMESIZE] of char; 
flags : integer; 
ptr: integer; 

end; 

type vwsurfst = array [1 . .DEVNAMESIZE] of char; 
type vwarr = array [1 . .MAXVSURF] of vwsurf; 

E.5. Function Declarations The list on the following pages is a complete alphabetical list of the Pascal func- 

tions in SunCore. 

function allocateraster (var rptr : rasttyp) : integer; external; 

function awaitanybutton (tim: integer ; var buttonnum: integer) : integer; external; 
function awtbuttongetloc2 (time : integer ; locatornum: integer; 

var buttonnum: integer; var x:real; var y:real) rinteger; external; 
function awtbuttongetval (time : integer ; valnum: integer; var buttonnum: integer; 
var val : real) : integer; external; 

function awaitkeyboard (tim: integer; keynum: integer ; var sptr:cct; 

var length : integer) : integer ; external; 
function awaitpick (time : integer ; picknum: integer ; var segnam: integer; 
var pickid: integer) : integer ; external; 

function awaitstroke2 (tim: integer; picknum: integer; asize : integer; var x:parr; 

var y:parr; numxy : integer) : integer ; external; 
function beginbatchupdate : integer ; external; 
function closeretainseg : integer; external; 
function closetempseg: integer; external; 

function createretainseg (segname : integer) : integer; external; 
function createtempseg : integer; external; 

function def colorindices (var surf acename : vwsurf ; il: integer; i2 : integer; 

var r:parr; var g:parr; var b:parr) :integer; external; 
function delallretainsegs : integer ; external; 

function delretainsegment (segname : integer) : integer ; external; 
function deselectvwsurf (var surf acename : vwsurf ): integer ; external; 
function endbatchupdate : integer; external; 

function f iletoraster (var rasfid:text; var rptr : rasttyp; var map:cmap) 

: integer; external; 

function f reeraster (var rptr : rasttyp) : integer ; external; 

function getmousestate (devclass : integer; devnum: integer; var x:real; 

var y:real; var buttons : integer) : integer; external; 
function getraster (var surfacename .-vwsurf ; xmin:real; xmax:real; ymin:real; 

ymax:real; xd:integer; yd:integer; var rptr : rasttyp) : integer; external; 
function getviewsurface (var surfacename : vwsurf ): integer; external; 
function initializecore (outputlevel : integer; inputlevel : integer; 

dimension : integer) : integer; external; 
function initializedevice (deviceclass : integer; devicenum: integer) 

: integer; external; 

function initializevwsurf (var surfacename : vwsurf ; typ: integer) 

: integer; external; 

function inqchar just (var ch just : integer ): integer ; external; 
function inqcharpath2 (var x:real; var y : real) : integer ; external; 
function inqcharpathS (var x:real; var y:real; var z : real) : integer; external; 
function inqcharprecision (var chquality : integer ): integer ; external; 
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function inqcharsize (var width:real; var height : real) : integer; external; 
function inqcharspace (var space : real) : integer; external; 
function inqcharup2 (var x:real; var y: real) : integer; external; 
function inqcharupS (var xrreal; var y:real; var z : real) : integer; external; 
function inqcolorindices (var surfacename : vwsurf ; il: integer; i2 : integer; 

var r:parr; var grparr; var b:parr) : integer; external; 
function inqcurrpos2 (var x:real; var y: real) : integer; external; 
function inqcurrpos3 (var x:real; var ytreal; var z : real) : integer ; external; 
function inqdetectability (var detect : integer) ; integer; external; 
function inqecho (devclass : integer; devnum: integer; var echotype : integer) 

: integer; external; 

function inqechoposition (devclass : integer; devnum: integer ; var x:real; 

var y: real) : integer; external; 
function inqechosurf ace (devclass : integer; devnum: integer; 

var surfacename : vwsurf ): integer; external; 
function inqf ill index (var color : integer) : integer; external; 
function inqf ont (var font : integer) : integer; external; 
function inqhigh lighting (var highlight : integer) : integer; external; 
function inqimgtransform2 (var sx:real; var sy:real; var a: real; var txrreal; 
var ty: real) : integer; external; 

function inqimgtransformS (var sx:real; var sy:real; var sz:real; var ax:real; 
var ay: real; var az:real; var tx:real; var ty:real; var tz:real) 

: integer; external; 

function inqimgxf ormtype (var segtype : integer) : integer; external; 
function inqimgtranslate2 (var tx:real; var ty: real) : integer; external; 
function inqimgtranslateS (var tx:real; var ty:real; var tz:real) 

: integer; external; 

function inqinvcompmatrix ( var iarray: ivarray) : integer; external; 
function inqkeyboard (keynum: integer ; var buf size : integer ; var string:cct; 

var pos : integer) : integer; external; 
function inqline index (var color : integer) : integer; external; 
function inqlinestyle (var linestyle : integer) : integer ; external; 
function inqlinewidth (var linewidth : real) : integer; external; 

function inqlocator2 (locnum: integer; var x:real; var y: real) : integer; external; 
function inqmarkersymbol (var mark : integer) : integer; external; 
function inqndcspace2 (var width:real; var height : real) : integer ; external; 
function inqndcspaceS (var width: real; var height:real; var depth:real) 

: integer; external; 

function inqopenretainseg (var segname : integer) : integer; external; 
function inqopentempseg (var open : integer) : integer; external; 
function inqpen(var pen: integer) : integer; external; 
function inqpickid(var pick : integer) : integer; external; 
function inqpolyedgestyle (var pestyle : integer) : integer ; external; 
function inqpolyintrstyle (var pistyle : integer) : integer ; external; 
function inqprimatt ribs (var defprim:primattr) : integer; external; 
function inqpro jection (var ptype : integer; var dx:real; var dy:real; 

var dz : real) : integer; external; 
function inqrasterop (var rastop : integer) : integer; external; 
function inqretainsegname (arraycnt : integer; var seglist : iarr; 

var segcnt : integer) : integer; external; 
function inqretainsegsurf (segname : integer; arraycnt : integer ; 

var surf list :vwarr; var surf cnt : integer) : integer; external; 
function inqsegdetectable (segname : integer; var dtable : integer) 

sun Revision A, of 9 May 1988 

microsystems 






Appendix E — Using SunCore with Pascal Programs 1 87 



: integer; external; 

function inqseghighlight (segname : integer; var highlight : integer) 

: integer; external; 

function inqsegimgxform2 (segname : integer; var sxrreal; var syireal; 

var arreal; var txrreal; var ty: real) : integer ; external; 
function inqsegimgxformS (segname : integer; var sxzreal; var sy:real; 
var sz:real; var rx:real; var ryrreal; var rzrreal; var tx:real; 
var tyrreal; var tz : real) : integer; external; 
function inqsegimgxfrmtyp (segname : integer; var segtype : integer) 

: integer; external; 

function inqsegimgxlate2 (segname : integer; var txtreal; var tyrreal) 

: integer; external; 

function inqsegimgxlateS (segname : integer; var sxrreal; var syrreal; 
var sz : real) : integer; external; 

function inqsegvisibility (segname : integer ; var visible : integer ) 

: integer; external; 

function inqstroke (strokenum: integer; var buf size : integer ; var distzreal; 

var time : integer) : integer; external; 
function inqtextextent2 (var string:cct; var dxrreal; var dyireal) 

: integer; external; 

function inqtextextentS (var string:cct; var dxireal; var dy:real; var dz:real) 
: integer; external; 

function inqtextindex (var color : integer) : integer ; external; 
function inqvaluator (valnum: integer; var init:real; var low: real; 
var high : real) : integer ; external; 

function inqviewdepth (var fdistzreal; var bdist : real) : integer ; external; 
function inqviewplanedist (var vdist : real) : integer ; external; 
function inqviewplanenorm (var dxrreal; var dy:real; var dzrreal) 

: integer; external; 

function inqviewrefpoint (var rx:real; var rytreal; var rzrreal) 

•.integer; external; 

function inqviewup2 (var dxrreal; var dy: real) : integer; external; 

function inqviewupS (var dxireal; var dyireal; var dz : real) : integer; external; 

function inqvwgcntrlparms (var wc 1 ip : integer; var f clip : integer; 

var bclip : integer ; var typ: integer) : integer; external; 
function inqviewingpa rams (var viewparm: vwprmtype) : integer ; external; 
function inqviewport2 (var xmin:real; var xmaxrreal; var yminrreal; 
var ymax:real) : integer; external; 

function inqviewport3 (var xmintreal; var xmaxrreal; var yminrreal; 

var ymaxrreal; var zminrreal; var zmax : real) : integer ; external; 
function inqvisibility (var visible : integer) : integer; external; 
function inqwindow (var uminrreal; var umaxrreal; var vminrreal; 

var vmax : real) r integer ; external; 
function inqworldmatrix2 (var iarray : ivarrayl) : integer ; external; 
function inqworldmat rix3 (var iarray : ivarray) : integer; external; 
function lineabs2 (x: real; y : real) : integer ; external; 
function lineabs3 (x: real; yrreal; z : real) : integer ; external; 
function linerel2 (x : real; y : real) : integer ; external; 
function linerel3 (x : real; yrreal; z : real) : integer; external; 
function mapndctoworld2 (ndx : real ; ndyrreal; var wldxrreal; var wldyrreal) 

: integer; external; 

function mapndctoworld3 (ndx: real; ndyrreal; ndzrreal; var wldxrreal; 
var wldyrreal; var wldz : real) : integer; external; 
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function mapworldtondc2 (wldx: real; wldyrreal; var ndx:real; var ndyrreal) 

: integer; external; 

function mapworldtondcS (wldx: real; wldyrreal; wldzrreal; var ndxireal; 

var ndy:real; var ndz : real) : integer; external; 
function markerabs2 (mx: real; my : real) : integer; external; 
function markerabs3 (mx: real; myrreal; mz : real) : integer; external; 
function markerrel2 (dx: real; dy: real) : integer; external; 
function markerrelS (dx: real; dyrreal; dz : real) : integer; external; 
function moveabs2 (x: real; y: real) : integer; external; 
function moveabsS (x: real; y:real; z : real) : integer; external; 
function moverel2 (x: real; y: real) : integer; external; 
function moverelS (x: real; y:real; z : real) : integer; external; 
function newframe ; integer; external; 

function pasloc (function f : integer) : integer; external; 
function polygonabs2 (var xcoor:parr; var ycoor:parr; n: integer) 

: integer; external; 

function polygonabsS (var xcoor:parr; var ycoor:parr; var zcoor:parr; n: integer) 
: integer; external; 

function polygonrel2 (var xcoor:parr; var ycoor:parr; n:integer) 

: integer; external; 

function polygonrelS (var xcoor:parr; var ycoor:parr; var zcoor:parr; n: integer) 
: integer; external; 

function polylineabs2 (var xcoor:parr; var ycoor:parr; n:integer) 

: integer; external; 

function polylineabs3 (var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n : integer) : integer; external; 

function polylinerel2 (var xcoor:parr; var ycoor:parr; n:integer) 

: integer ; external ; 

function polylinerel3 (var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n : integer) : integer; external; 

function polymarkerabs2 (var xcoor:parr; var ycoor:parr; n:integer) 

: integer; external; 

function polymarkerabs3 (var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n : integer) : integer; external; 

function polymarkerrel2 (var xcoor:parr; var ycoor:parr; n:integer) 

: integer; external; 

function polymarkerrel3 (var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n : integer) : integer; external; 

function printerror (var string:cct; error : integer) : integer; external; 
function putraster (var rptr:rasttyp) : integer; external; 
function put text (var string: cct) : integer; external; 

function rastertof ile (var rptr : rasttyp; var map:cmap; var rasfid:text; 
n : integer) : integer; external; 

function renameretainseg (segname : integer; newname: integer) : integer; external; 

function reportrecenterr (var error : integer) : integer; external; 

function restoresegment (segname : integer; var f name : cct) : integer; external; 

function savesegment (segname : integer; var fname : cct ): integer; external; 

function selectvwsurf (var surf acename :vwsurf) : integer; external; 

function setbackclip (onoff : integer) : integer; external; 

function setchar just (ch just : integer) : integer; external; 

function set charpath2 (dx: real; dy: real) : integer; external; 

function set charpath3 (dx: real; dy:real; dz : real) : integer; external; 

function setcharprecision (chquality: integer) : integer; external; 
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function setcharsize (chwid: real; chht : real) : integer; external; 
function setcharspace (space : real) : integer; external; 
function setcharup2 (dx: real; dy: real) : integer; external; 
function setcharupS (dx: real; dyireal; dz : real) : integer; external; 
function setcoordsystype (typ : integer) : integer; external; 
function setdetectability (detect : integer) : integer ; external; 
function setdrag (drag: integer) : integer; external; 

function setecho (devclass : integer ; devnum: integer; echotype : integer) 

: integer; external; 

function setechogroup (devclass : integer; var devarray : iarr ; n: integer; 
echotype : integer) : integer; external; 

function setechoposition (devclass : integer; devnum: integer ; x:real; y:real) 

: integer; external; 

function setechosurface (devclass : integer; devnum: integer ; 

var surf acename :vwsurf) : integer; external; 
function setfillindex (color : integer) : integer; external; 
function setfont (font : integer) : integer; external; 
function setfrontclip (onoff : integer) : integer; external; 
function sethighlighting (highlight : integer) : integer; external; 
function setimgtransform2 (sx: real; sy:real; a:real; tx:real; ty:real) 

: integer; external; 

function set imgt ransf orm3 (sx: real; sy:real; sz:real; ax: real; ay: real; az:real; 

tx:real; ty:real; tz : real) : integer; external; 
function setimgxformtype (segtype : integer) : integer; external; 
function setimgtranslate2 (tx: real; ty: real) : integer; external; 
function setimgtranslateS (tx: real; ty:real; tz : real) : integer ; external; 
function setkeyboard (keynum: integer ; buf size : integer; var string :cct; 
pos: integer) : integer; external; 

function setlightdirect (dx : real; dy:real; dz : real) : integer ; external; 
function setlineindex (color : integer) : integer; external; 
function setlinestyle (style : integer) : integer; external; 
function setlinewidth (width : real) : integer ; external; 

function setlocator2 (locnum: integer; x:real; y: real) : integer ; external; 

function setmarkersymbol (mark : integer) : integer; external; 

function setndcspace2 (width : real; height : real) : integer ; external; 

function setndcspaceS (width : real; height:real; depth : real) : integer ; external; 

function setoutputclip (onoff : integer) : integer; external; 

function setpen (pen : integer) : integer ; external; 

function setpick (pickid: integer; aperture : real) : integer ; external; 
function setpickid (pickid: integer) : integer; external; 
function setpolyedgestyle (pestyle : integer) : integer; external; 
function setpolyintrstyle (pistyle : integer) : integer ; external; 
function setprimattribs (var defprim:primattr) : integer ; external; 
function setpro ject ion (ptype : integer ; dx:real; dy:real; dz:real) 

: integer; external; 

function set rasterop (rop : integer ): integer ; external; 

function set segdetect able (segname : integer; detectbl : integer) : integer ; external; 
function set seghighlight (segname : integer; highlight : integer) : integer; external; 
function set segimgxform2 (segname : integer ; sx:real; sy:real; a:real; tx:real; 
ty: real) : integer ; external; 

function setsegimgxformS (segname : integer ; sx:real; sy:real; sz:real; rx:real; 

ry:real; rz:real; tx:real; ty:real; tz : real) : integer; external; 
function set segimgxlate2 (segname : integer; tx:real; ty: real) : integer; external; 
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function setsegimgxlateS (segname : integer ; tx:real; ty:real; tzrreal) 

: integer; external; 

function setsegvisibility (segname : integer; visible : integer) : integer; external; 
function set shadingparams (amb: real; diftreal; spec: real; flood: real; bump: real; 

hue: integer; style : integer) : integer; external; 
function setstroke (strokenum: integer; buf size : integer; dist:real; time : integer) 
: integer; external; 

function settextindex (color : integer) : integer; external; 

function setvaluator (valnum: integer; initcreal; low:real; high : real) : integer; 
external; 

function setvertexindices (var x:iarr; n : integer) : integer; external; 
function setvertexnormals (var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n : integer) : integer; external; 

function setviewdepth (near : real; far : real) : integer; external; 
function setviewplanedist (dist : real) : integer; external; 

function set viewplanenorm (dx: real; dy:real; dz : real) : integer; external; 
function setviewrefpoint (x:real; y:real; z : real) : integer; external; 
function setviewup2 (dx: real; dy: real) : integer; external; 
function setviewup3 (dx: real; dy:real; dz : real) : integer; external; 
function setviewingparams (var viewparm:vwprmtype) : integer; external; 
function setviewport2 (xmin:real; xmax:real; ymin:real; ymax:real) 

: integer; external; 

function set viewport 3 (xmin: real; xmax:real; ymin:real; ymax:real; zminireal; 
zmax: real) : integer; external; 

function setvisibility (visibility : integer) : integer; external; 
function setwindow (umin: real; umax:real; vmin:real; vmax:real) 

: integer; external ; 

function setwindowclip (onoff : integer) : integer; external; 
function setworldmatrix2 (var iarray: ivarrayl) : integer; external; 
function setworldmatrix3 (var iarray : ivarray) : integer; external; 
function setzbuf fercut (var surfacename : vwsurf ; var x:parr; var z:parr; 
n: integer) : integer; external; 

function sizeraster (var surfacename : vwsurf ; xmin:real; xmax:real; ymin:real; 

ymax:real; var rptr : rasttyp) : integer; external; 
function terminatecore : integer; external; 

function terminatedevice (devclass : integer ; devnum: integer) : integer; external; 
function terminatevwsurf (var surfacename : vwsurf ): integer; external; 

Note: since vwarr is an array of MAXVSURF viewsurfaces, arraycnt should be MAXVSURF. 

function inqsegdetectable (segname : integer; var dtable : integer) 

: integer; external ; 

function inqseghighlight (segname : integer; var highlight : integer) 

: integer; external ; 

function inqsegimgxform2 (segname : integer; var sx:real;var sy:real; 
var a: real; var tx: real; var tyireal 
): integer; external; 

function inqsegimgxform3 (segname: integer; var sx:real;var sy:real; 
var sz: real; var rx: real; var ry:real; 
var rz: real; var tx: real; var ty: real; var tz:real 
): integer; external; 

function inqsegimgxfrmtyp (segname : integer; var segtype : integer) 

: integer; external; 

function inqsegimgxlate2 (segname: integer; var tx:real;var ty:real) 
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: integer; external; 

inqsegimgxlateS (segname : integer; var sx:real;var syrreal; 

var sz : real) : integer; external; 
inqsegvisibility (segname : integer; var visible : integer) : 
integer; external; 

inqstroke (strokeniim: integer; var bufsize : integer; var 
dist : real; var time : integer) : integer; external; 
inqtextextent2 (var string :cct; var dxrreal; var dy:real 
) : integer; external; 

inqtextextentS (var string:cct;var dxrreal; var dyireal 
; var dz : real) : integer; external; 
inqtextindex (var color : integer) : integer; external; 

inqvaluator (valnum: integer; var init : real; var low:real;var highrreal) 

: integer; external; 

inqviewdepth (var fdist : real; var bdist:real) 

: integer; external; 

inqviewplanedist (var vdist : real) : integer; external; 
inqviewplanenorm (var dx:real; var dy:real; 

var dz : real) : integer; external; 
inqviewref point (var rx:real; var ryrreal; 

var rz : real) : integer ; external; 
inqviewup2 (var dxrreal; var dyrreal 
) ‘.integer; external; 
inqviewupS (var dxrreal; var dyrreal; 

var dz r real) r integer; external; 
inqvwgcntrlparms (var wclipr integer; var f clip r integer; 
var bclip r integer; var typr integer) 
r integer; external; 

inqviewingpa rams (var viewparmr vwprmtype) r integer; external; 
inqviewport2 (var xminrreal; var xmaxr real; var yminrreal;var ymaxrreal 
) ‘.integer; external; 

inqviewportS (var xminrreal; var xmax: real; var ymin: real; var ymaxrreal 
;var zmin r real; var zmaxrreal) 
r integer; external; 
inqvisibility (var visible r integer) 

: integer; external; 

inqwindow (var uminrreal; var umaxr real; var vminr real; var vmaxrreal 
) : integer; external; 

inqworldmatrix2 (var iarrayrivarrayl) r integer; external; 
inqworldmatrixS (var iarrayrivarray) r integer; external; 
lineabs2 (x r real;y : real) rinteger; external; 
lineabsS (x r real;yr real; z r real) rinteger; external; 
linerel2 (x: real; y: real) rinteger; external; 
linerelS (xr real; yr real; z r real) rinteger; external; 
mapndctoworld2 (ndxrreal; ndyrreal; 

var wldxrreal; var wldyrreal) 
rinteger; external; 

mapndctoworldS (ndxr real; ndyrreal; ndzrreal; 
var wldxrreal; var wldyrreal 
; var wldzrreal) 
rinteger; external; 
mapworldtondc2 (wldxrreal; wldyrreal; 
var ndxrreal; var ndyrreal) 
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: integer; external; 

function mapworldtondc3 (wldx: real; wldyrreal; wldzrreal; 
var ndxrreal; var ndytreal 
; var ndz : real 
):integer; external; 

function markerabs2 (mx:real;my: real) : integer; external; 
function markerabsS (mx : real; my : real;mz : real) : integer; external; 
function markerrel2 (dx: real; dy: real) ; integer; external; 
function markerrelS (dx : real; dy : real; dz: real) : integer; external; 
function moveabs2 (x:real;y: real) : integer; external; 
function moveabs3 (x:real;y :real; z :real) :integer; external; 
function moverel2 (x:real;y: real) : integer; external; 
function moverel3 (x: real;y:real; z : real) : integer; external; 
function newframe : integer; external; 
function pasloc (function f:integer 
): integer; external; 

function polygonabs2 (var xcoor:parr; var ycoor:parr; 
n : integer) : integer ; external; 

function polygonabs3 (var xcoorrparr; var ycoor :parr; var zcoorrparr; 

n : integer) : integer ; external; 
function polygonrel2 (var xcoor:parr; var ycoorrparr; 
n: integer) : integer; external; 

function polygonrel3 (var xcoor:parr; var ycoor :parr; var zcoorrparr; 

n : integer) : integer ; external; 
function polylineabs2 (var xcoortparr; var ycooriparr; 
n; integer) .-integer; external; 

function polylineabs3 (var xcoor:parr; var ycoor : parr; var zcooriparr; 

n : integer) : integer; external; 
function polylinerel2 (var xcoor :parr; var ycoor:parr; 
n : integer) : integer; external; 

function polylinerel3 (var xcoor :parr; var ycoor :parr; var zcoor:parr; 

n : integer) : integer; external; 
function polymarkerabs2 (var xcoor:parr; var ycoor:parr; 
n : integer) : integer; external; 

function polymarkerabs3 (var xcoor :parr; var ycoor :parr; var zcoor:parr; 

n : integer) : integer; external; 
function polymarkerrel2 (var xcoorrparr; var ycoor:parr; 
n : integer) : integer; external; 

function polymarkerrel3 (var xcoor:parr; var ycoor :parr; var zcoorrparr; 
n : integer) : integer; external; 

function printerror (var string rcct; error : integer) : integer; external; 
function putraster (var rptr : rasttyp) : integer; external; 
function puttext(var string : cct) : integer; external; 
function rastertof ile (var rptr : rasttyp; var maprcmap; rasfid: integer 
): integer; external; 

function renameretainseg (segname : integer ;newname : integer) : integer; external; 
function reportrecenterr (var error : integer) : integer; external; 
function restoresegment (segname : integer; var f name : cct) : integer; external; 
function savesegment (segname : integer; var fname : cct ): integer; external; 
function selectvwsurf (surf acename : vwsurf 
): integer; external; 

function setbackclip (onoff : integer) : integer ; external; 
function setchar just (ch just : integer) : integer; external; 
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set charpath2 (dx: real; dy: real) : integer; external; 

set charpath3 (dx: real; dy: real;dz : real) : integer; external; 

setcharprecision (chquality: integer) : integer; external; 

setcharsize (chwid: real; chht : real) : integer; external; 

setcharspace (space : real) : integer; external; 

set charup2 (dx: real; dy: real) : integer; external; 

set charupS (dx: real; dy: real;dz :real) : integer; external; 

setcoordsystype (typ: integer) : integer; external; 

setdetectability (detect : integer) : integer; external; 

setdrag (drag: integer) : integer; external; 

setecho (devclass : integer ;devnum: integer; 

echotype : integer) : integer; external; 
setechogroup (devclass : integer; var devarray: iarr;n:integer; 

echotype : integer) : integer; external; 
setechoposition (devclass : integer ;devnuin: integer; 

x: real; y: real) : integer; external; 
setechosurf ace (devclass : integer;devnum:integer; 
surfacename : vwsurf ) : integer; external; 
setfillindex (color : integer) : integer; external; 
setf ont (font : integer) : integer; external; 
setfrontclip (onoff : integer) : integer; external; 
sethighlighting (highlight : integer) : integer; external; 
setimgtransform2 (sx: real; sy : real; a : real 

;tx:real; ty: real) : integer; external; 
setimgtransf orm3 (sx ; real; sy : real; sz : real; 
ax: real; ay : real; az : real; 
tx:real; ty: real; tz : real) 

: integer; external; 

set imgxformtype (segtype : integer) :integer; external; 
set imgt ranslate2 (tx: real; ty: real) : integer; external; 
setimgtranslate3 (tx : real; ty: real; tz : real) : integer; external; 
set keyboard (keynum: integer ;buf size : integer; var string:cct; 

pos : integer) : integer; external; 
setlightdirect (dx: real; dy : real; dz: real 
) : integer; external; 

setlineindex (color : integer) : integer; external; 
setlinestyle (style : integer) : integer; external; 
setlinewidth (width : real) : integer; external; 

setlocator2 (locnum:integer;x:real;y:real) : integer; external; 
setmarkersymbol (mark : integer) : integer; external; 
setndcspace2 (width : real; height : real) :integer; external; 
setndcspace3 (width : real; height : real; depth : real) 

: integer; external; 

setoutputclip (onoff : integer) ‘.integer; external; 
setpen (pen : integer) : integer; external; 

setpick (picknum: integer; aperture: real) : integer; external; 
setpickid(pickid: integer) : integer; external; 
setpolyedgestyle (pestyle : integer) :integer; external; 
setpolyintrstyle (pistyle -.integer) :integer; external; 
setprimattribs (var defprim:primattr) : integer; external; 
setpro jection (ptype : integer;dx : real; dy : real;dz : real) 

: integer; external; 

setrasterop (rop : integer) : integer; external; 
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function set segdetectable (segname : integer; detectbl : integer) 

: integer; external; 

function setseghighlight (segname : integer; highlight : integer) 

: integer; external; 

function setsegimgxf orm2 (segname : integer; sx: real; sy : real; a : real; 

tx: real; ty: real) : integer; external; 
function setsegimgxformS (segname : integer; sxrreal; syrreal; 

szrreal; rxrreal; ryzreal; rzireal 
; txzreal; tyzreal; tzrreal 
): integer; external; 

function setsegimgxlate2 (segname : integer;tx: real; tyireal 
) .'integer; external; 

function setsegimgxlateS (segname : integer; tx: real; ty : real; tz : real 
): integer; external; 

function set segvisibility (segname : integer; visible : integer) : integer; external; 
function setshadingparams (amb : real;dif : real; spec : real; flood: real; 
bump : real ; hue : integer ; style : integer 
): integer; external; 

function setstroke (strokenum: integer;buf size : integer; 
dist : real; time : integer) 

: integer; external; 

function settextindex (color : integer) : integer; external; 
function setvaluator (valnum: integer; init : real; low: real; high : real) 

: integer; external; 

function setvertexindices (var x: iarr;n: integer) : integer; external; 
function setvertexnormals (var xcoorzparr; var ycoor :parr; var zcoorzparr; 
n : integer) : integer ; external; 

function setviewdepth (near : real; far : real) : integer; external; 
function setviewplanedist (dist : real) : integer; external; 
function setviewplanenorm (dx: real; dy : real; dz : real) : integer ; external; 
function setviewrefpoint (x: real; y: real; z : real) : integer ; external; 
function set viewup2 (dx: real; dy: real) : integer; external; 
function setviewupS (dx: real; dy : real ;dz: real) : integer; external; 
function setviewingparams (var viewparm: vwprmtype) : integer; external; 
function setviewport2 (xmin: real;xmax: real;ymin: real;ymax: real) : 
integer; external; 

function set viewport 3 (xmin: real; xmax: real ;ymin: real; ymax: real; zmin : real; zmax: real) 
: integer; external; 

function setvisibility (visibility : integer) : integer; external; 
function setwindow (umin : real ;umax: real; vmin : real; vmax: real) 

: integer; external; 

function setwindowclip (onoff : integer) : integer; external; 
function setworldmatrix2 (var iarray: ivarrayl) : integer; external; 
function setworldmatrixS (var iarray : ivarray) : integer; external; 
function setzbuf fercut (var surfacename : vwsurf ; var x:parr; 

var z :parr;n: integer) : integer; external; 
function sizeraster (var surfacename : vwsurf ; 

xmin : real; xmax: real;ymin : real; ymax: real; 
var rptr : rasttyp) : integer; external; 
function terminatecore : integer; external; 

function terminatedevice (devclass : integer; devnum: integer) zinteger; external; 
function terminatevwsurf (var surfacename : vwsurf ): integer; external; 
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Hardware Floating Point SunCore 

Libraries 



SunCore programs intended for Sun workstations with hardware floating point 
support may use alternative SunCore libraries which provide higher floating 
point performance. Separate libraries are provided for each of the floating point 
options described below. 

The presence of one of these options is independent of whether a Graphics Pro- 
cessor is present. It is not necessary to use one of these special libraries to take 
advantage of the Graphics Processor. 

For Sun-2 workstations, the only available floating point hardware is the SKY 
floating point processor. The appropriate library in this case is 
/usr/lib/libcoresky . a. A program linked with this library will only run 
on a Sun workstation with a SKY board. 

For Sun-3 workstations, two floating point hardware options are available. For 
Sun workstations with the MC6888 1 floating point co-processor, the appropriate 
library is /usr/lib/libcore68881 . a. A program linked with this library 
will only run on a Sun workstation with an MC6888 1. For Sun workstations 
with a Floating Point Accelerator (FPA), the appropriate library is 
/usr/lib/libcorefpa . a. A program linked with this library will only run 
on a Sun workstation with an FPA. 



C programs written with SunCore can be compiled with the following command 
line: 




In these command lines, xxx should be replaced with the appropriate symbol 
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from Table F-1. 

Table F- 1 Floating Point Libraries 



Symbol 


Description 


sky 


Sky floating point board 


68881 


MC6888 1 floating point co-processor 


fpa 


Floating Point Accelerator 



If compiling and linking are done in separate steps, the -txxx option must be 
specified in the linking stage. The - txxx option may also be used in the compil- 
ing step. Different modules within a program cannot be compiled with different 
hardware floating point switches, but modules compiled with -fsoftor- 
f switch can be combined with modules compiled with a single type of 
hardware switch. See the manual pages for cc(l), f 77(1) and pc(l) for details. 

To compile and link a program to mn on any configuration of hardware for a 
specific processor type (Sun-2 or Sun-3), use the -f switch option for compil- 
ing and linking. The -f switch option will cause the compiler to take advan- 
tage of floating point hardware if it is available. Otherwise, the compiler will 
emulate this floating point support with software. See cc(l), f 77(1) or pc(l) 
for details. The -Icore option links with the generic SunCore library, 

/usr / lib/libsuncor e . a. Note that different binary versions of a program 
are required for Sun-2 and Sun-3 processors. 

Many graphics programs written in C do not require the precision implied by 
evaluating floating point expressions in double precision. The -f single 
option may be used to force single precision evaluation of arithmetic expressions 
involving only float quantities (see cc(l)). 
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Error Messages 



SunCore does not use the error numbers suggested by the ACM CORE standard. 
The following table matches an error number with the error message: 



T able G- 1 SunCore Error Messages 



Error 

Number 



Description 



0 The CORE SYSTEM has already been initialized. 

1 The specified level cannot be supported. 

2 The surface has already been initialized. 

3 No physical surface is associated with the specified logical sur- 
face . 

4 The CORE SYSTEM has not been initialized. 

5 The specified surface has not been initialized. 

6 The specified surface is already selected. 

7 The specified surface was not selected. 

8 A segment is open. 

9 The specified surface is not selected. 

10 The specified surface has not been deselected. 

11 This function has already been called once. 

12 A segment has been opened. 

13 A value specified for a default attribute is improper. 

14 The specified segment does not exist. 

15 The VIEW SURFACE ARRAY is not large enough. 

16 Segment list overflow, can't create segment. 

17 There has been no 'end batch' since last 'begin batch' . 

18 There has been no corresponding 'begin batch' . 

19 A viewing function has been invoked, or a segment has been 
created. 

20 The value for TYPE is improper. 

21 No segment is open. 

22 n is <= 0. 

23 String contains an illegal character. 

24 The vectors established by CHARSPACE and CHARUP are parallel. 

25 Invalid marker table offset. 

26 Invocation when no open segment. 

27 Invalid attribute value. 
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T able G- 1 SunCore Error Messages — Continued 

Error Description 

Number 

28 Invalid segment type. 

29 Invalid segment number. 

30 Invalid image transformation for the segment . 

31 A retained segment named SEGNAME already exists. 

32 The segment type is inconsistent with the current 
IMAGE_TRANSFORM . 

33 No view surface is currently selected. 

34 The current viewing specification is inconsistent. 

35 No view surfaces have been initialized. 

36 There is an existing retained segment named NEW_NAME . 

37 There is no retained segment named SEGMENT_NAME . 

38 No characters in string (n=0) . 

39 Dx, dy, and dz, are all zero: no direction can be established. 

40 MIN is not less than MAX, for u or v bounds. 

41 FRONT_DISTANCE exceeds BACK_DISTANCE; back clip plane is in 
front . 

42 'ndcsp2' or 'ndcsp3' has been invoked since SunCore was last ini- 
tialized. 

43 The invocation of 'ndcspx' is too late, default values have been 
assumed. 

44 A parameter value is greater than 1, or is less than or equal to 

0 . 

45 Neither parameter has a value of 1. 

46 Viewport extent is outside of normalized device coordinate space. 

47 MIN is not less than MAX, for x, y, or z bounds. 

48 Specified device already enabled. 

49 DEVICE_CLASS or DEVICE_NUM invalid. 

50 DEVICE_CLASS invalid. 

51 Specified device is not enabled. 

52 LOCATOR_NUM is invalid. 

53 The specified LOCATOR device is not enabled. 

54 VALUATOR_NUM is invalid. 

55 The specified VALUATOR device is not enabled. 

56 The TIME value is less than zero. 

57 EVENT_CLASS and EVENT_NUM do not specify a valid event device. 

58 EVENT_CLASS is not a legal event device class. 

59 The specified association already exists. 

60 EVENT_CLASS or SAMPLED_CLASS reference invalid or wrong type of 
class . 

61 EVENT_NUM or SAMPLED_NUM are invalid device numbers for their 
classes . 

62 The specified association does not exists. 

63 The current event report is not from a PICK device. 

64 The current event report is not from a KEYBOARD event. 
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T able G- 1 SunCore Error Messages — Continued 



Error 

Number 



65 




Input string was not large enough to hold the string centered by 



When event occurred, the LOCATOR device was not enabled or was 
not associated with the event device. 

When event occurred, the VALUATOR device was not enabled or was 
not associated with the event device. 

XECHO and YECHO specify positions outside NDC space. 

PICK_NUM does not specify a valid PICK device. 

LOCATOR_NUM does not specify a valid LOCATOR device . 

XLOC,YLOC specify a position outside normalized device coordinate 
space . 

VALUATOR_NUM is not a valid VALUATOR device. 

L0W_VALUE is greater than HIGH_VLAUE . 

INITIAL_VALUE lies outside the range defined by LOW_VALUE and 
HIGH_VALUE. 

KEYBOARD_NUM is not a valid KEYBOARD device. 

BUFFER_SIZE is <= zero or > the defined maximum. 

BUTTON_NUM is not a valid BUTTON device. 

Incorrect arguments for the specified function. 

Incorrect argument count for the specified function. 

Specified function not supported. 

More than MAXPOLY vertices in polygon. 

Invalid Viewing Specification. Viewing Matrix Unchanged! 

Invalid view surface name. 

Selected view surface cannot support hidden surfaces. 

No other view surface can be initialized at this time. 

Raster depth is 1 or 8 bit pixels only. 

Unable to allocate space for virtual memory display list. 

Memory allocation failure. 

Error in view reference point. 

Error in view plane normal. 

Error in view plane distance. 

Error in view depth . 

Error in projection. 

Error in window. 

Error in view up direction. 

Error in viewport . 

Set_ndc_space_2 or set_ndc_space_3 has already been invoked. 

The default NDC space has already been established. 

A parameter is not in the range of 0 to 1. 

Neither width nor height has a value of 1. 

Width or height is 0. 

STROKE_NUM is not a valid STROKE device . 

Input device is already initialized. 

Input device is not initialized. 
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T able G- 1 SunCore Error Messages — Continued 



105 DEVICE_CLASS is not a valid device class. 

106 Invalid echo type for PICK device. 

107 Invalid echo type for KEYBOARD device. 

108 Invalid echo type for STROKE device. 

109 Invalid echo type for LOCATOR device. 

110 Invalid echo type for VALUATOR device. 

111 Invalid echo type for BUTTON device. 

112 Echo position specified is outside NDC space. 

113 No BUTTON device is initialized. 

114 Invalid raster type. 

115 Fewer than 3 vertices in polygon. 



Error 

Number 



Description 
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Type and Structure Definitions 



This appendix lists the typ>es and structures used by SunCore functions. The 
definition of these types and structures can be found in <usercore . h>. 



/ 

#def ine 


BASIC 


0 


. 1 1 1 II 

/* Core output levels */ 


#def ine 


BUFFERED 


1 




#def ine 


BUTTON 


2 




#def ine 


CENTER 


2 




#def ine 


CHARACTER 


1 




#def ine 
#def ine 


CMR 4 

CMRBOLD 


5 




#def ine 


COMPLETE 


2 




#def ine 


CONSTANT 


0 


/* polygon shading modes */ 


#def ine 


DASHED 


2 




♦define 


DEFAULT VWSURF(ddname) 0, ddname, 0, 0, 0, 0} 


♦define 


DEVNAMESIZE 


20 




♦define 


DOTD ASHED 


3 




♦define 


DOTTED 


1 




♦define 


DYNAMICA 


2 




♦define 


DYNAMICB 


3 




♦define 


DYNAMICC 


4 




♦define 


FALSE 


0 




♦define 


GACHA 


1 




♦define 


GACHABOLD 


3 




♦define 


GALLANT 


0 


/* raster font constants */ 


♦define 


GOURAUD 


1 




♦define 


GREEK 


1 




♦define 


KEYBOARD 


1 




♦define 


LEFT 


1 




♦define 


LOCATOR 


3 




♦define 


MAXVSURF 


5 


/* view surfaces; maximum number of */ 


♦define 


NOINPUT 


0 


/* Core input levels */ 


♦define 


NONE 


1 


/* segment types */ 


♦define 


NORMAL 


0 


/* rasterop selection */ 


♦define 


NULL VWSURF 


{" 


", 0, 0, 0, 0, 0, 0} 


♦define 


OFF 0 


/* 


char justify constants */ 


♦define 


OLDENGLISH 


3 




♦define 


ORROP 


2 




♦define 


PARALLEL 


0 


/* transform constants */ 


♦define 


PERSPECTIVE 


1 




♦define 




PHONG 


2 


J 
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#def ine 


PICK 


0 


/* 


input device constants */ 


#def ine 


PLAIN 


0 


/* 


polygon interior style */ 


#def ine 


RIGHT 


3 






#def ine 


ROMAN 


0 


/* 


vector font select constants 


#def ine 


SAIL 


2 






#def ine 


SCRIPT 


2 






#def ine 


SHADED 


1 






#def ine 


SOLID 


0 


/* 


line styles */ 


#def ine 


STICK 


4 






#def ine 


STRING 


0 






#def ine 


STROKE 


5 






#def ine 


SYMBOLS 


5 






#def ine 


SYNCHRONOUS 


1 






#def ine 


THREED 


1 






#def ine 


TRUE 


1 






#def ine 


TWOD 


0 


/* 


Core dimensions */ 


#def ine 


VALUATOR 


4 






#def ine 


VWSURF_NEWFLG 


1 




#def ine 


XFORM2 


3 






#def ine 


XFORM3 


3 






#def ine 


XLATE2 


2 






#def ine 


XLATE3 


2 






#def ine 


XORROP 


1 






static : 


struct { 


/* 


default primitive attributes */ 



int lineindx; 
int fillindx; 
int textindx; 
int linestyl; 
int polyintstyl; 
int polyedgstyl; 
float linwidth; 
int pen; 
int font ; 

float chwidth, chheight ; 

float chup[4], chpath[4], chspace[4]; 

int chjust; 

int chqualty; 

int marker; 

int pickid; 

int rasterop; 

} PRIMATTS = {1,1,1, SOLID, PLAIN, SOLID, 0.0,0, STICK, 11. ,11., 

{ 0 ., 1 ., 0 ., 1 .},{ 1 ., 0 ., 0 ., 1 .}, { 0 ., 0 ., 0 ., 1 .}, 

OFF, STRING, 42 , 0 , NORMAL } ; 

Struct vwsurf { 

char screenname [DEVNAMESIZE] ; 

char windowname [DEVNAMESIZE] ; 

int windowfd; 

int (*dd)(); 

int instance; 

int cmapsize; 

char cmapname [DEVNAMESIZE] ; 

^ . 
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int flags; 


N 


char **ptr; 




}; 




V 
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Example Program 



This appendix contains an example program that uses a number of SunCore's 
facilities. The example is called factory. It displays a factory building with a 
smokestack and a cloud of smoke puffing out. Silicon chips move in at one end 
of the building, and Sun Workstations come out of the other end. 

Facilities displayed by this simple example include texturing, translation, scaling, 
and output clipping. The example is presented function by function, with an 
accompanying narrative. 

I.l. Declarations and the The first line in a SunCore application program should include the file 

Main Program <usercore.h> which contains the definitions required for using the SunCore 

graphics package. The factory program also has some definitions stored in 
the file factory . h. 

Figure I-l factory.h Header File 



#def ine 
#def ine 


FACTORY 10 
CLOUD 9 






#def ine 


WORKSTATION 1 


1 




#def ine 


WORKSTATION 2 


2 




#def ine 
#def ine 
#def ine 
#def ine 
< 


WORKS TAT ION_3 
CHIP_1 4 
CHIP_2 5 
CHIP_3 6 


3 





Then there are some definitions. Then we define and initialize the variables that 
describe the outlines of the various objects in the picture: Then we have the main 
program: The first call in the program is to initialize SunCore, with an appropri- 
ate exit if there is an error returned: Then we initialize and select a view surface. 
Again, we exit if there was an error returned: Then we establish a viewport and a 
window. Note that we can set clipping on output — this is a SunCore extension 
to the ACM Core. Set up the color lookup table. Now make a temporary seg- 
ment for a title and border. Next we establish a segment for the factory. This 
segment is the simplest type, since we perform no transformations of any kind on 
it. Next we establish a segment for the cloud above the factory. This segment is 
subject to scaling, so we must allow for transformations. Lastly, we establish 
segments for the chips and the workstations. The chips and workstations will be 
moving across the picture, so these segments must allow translation. Notice that 
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we created the workstations all on top of each other, and also all the chips on top 
of each other. The actual spatial separation of the individual segments is handled 
in the main body of the animation code. 

Now we get to the body of the code which animates the picture. The outer for 
loop is done 100 times. The calls on the translation functions make the chips and 
workstations move. The inner for loop makes the cloud grow: Finally, when 
everything is done, we deselect the view surface, and terminate SunCore: The 
remainder of the demonstration program consists of the functions which fill in 
the details in the individual segments. 

Figure 1-2 main . c Function 

#include <usercore.h> 
tinclude "factory.h" 

static float delta[] = {0.0, 0.025, 2*0.025, 3*0.025, 4*0.025, 

5*0.025, 6*0.025, 7*0.025, 8*0.025, 9*0.025, 

10*0.025, 11*0.025, 12*0.025}; 
int pixwinddO ; /* device driver name for SunWindows */ 

/* on a monochrome display - see Appendix B */ 
struct vwsurf vsurf = DEFAULT_VWSURF (pixwindd) ; 

/* The DEFAULT_VWSURF macro */ 

/* is defined in <usercore.h> */ 

main ( ) 

{ 

short i, pO, pi, p2; 
float clx, cly, scale; 

if (initialize_core (DYNAMICB, NOINPUT, TWOD) ) 
exit (0 ) ; 

if (initialize_view_surface (Svsurf , FALSE)) 
exit ( 1 ) ; 

if (select_view_surface (Svsurf ) ) 
exit ( 1 ) ; 

set_viewport_2 (0 . 05, 0.95, 0.05, 0.7); 
set_window (30 . 0, 225.0, 30.0, 225.0); 
set_output_c lipping (TRUE) ; 
set_window_clipping (FALSE) ; 
create_temporary_segment () ; 
move_abs_2 (30 . 0, 30.0); 
line_rel_2 (0 . 0, 195.0); 
line_rel_2 (195.0, 0.0); 
line_rel_2 (0 .0, -195.0); 
line_rel_2 (-195.0, 0.0); 
set_charprec is ion (CHARACTER) ; 
set_charsize (14 . 0, 14.0); 
set_text_index(l) ; 
move_abs_2 (40 . 0, 200.0); 
text ("SunCore") ; 
close_temporary_segment ( ) ; 
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set_image_transf ormation_type (NONE) ; 
create_retained_seginent (FACTORY) ; 
factory (110 . 0, 60.0); 
close_retained_seginent () ; 
set_image_transf ormation_type (XFORM2) ; 
create_retained_segment (CLOUD) ; 
map_world_to_ndc_2 (120 . 0, 100.0, &clx, &cly) ; 
set_segment_image_transformation_2 (CLOUD, 0.05, 0.1, 

0.0, clx, cly + 0.02); 
cloud (0.0, 0.0); 
close_retained_segment () ; 
set_image_transf ormation_type (XLATE2) ; 

/* Draw the Sun Workstation Segment */ 
create_retained_segment (WORKSTATION_l) ; 
sunws (160.0, 60.0); 
close_retained_segment () ; 
create_retained_segment (WORKSTATION_2) ; 
sunws (160.0, 60.0); 
close_retained_segment () ; 
create_retained_segment (WORKS TAT ION_3) ; 
sunws (160.0, 60.0); 
close_retained_segment () ; 

/* Draw the Chip Segment */ 
create_retained_segment (CHIP_1) ; 
chip(20 .0, 70.0) ; 
close_retained_segment () ; 
create_retained_segment (CHIP_2) ; 
chip(20.0, 70.0); 
close_retained_segment () ; 
create_retained_segment (CHIP_3) ; 
chip (20.0, 70.0); 
close_retained_segment () ; 
pO = 0; 
pi = 4; 

p2 = 8; 

for (i=0; i<100; i++) { 

set_segment_image_translate_2 (WORKSTATION_l, delta [pO] , 0.0); 
set_segment_image_translate_2 ( WORKS TAT ION_2, delta [pi] , 0.0); 
set_segment_image_translate_2 (WORKSTATION_3, delta [p2] , 0.0); 
set_segment_image_translate_2 (CHIP_3, delta [p2] , 0.0); 
set_segment_image_translate_2 (CHIP_2, delta [pi] , 0.0); 
set_segment_image_translate_2 (CHIP_1, delta [pO] , 0.0); 

p0++; 

pl++; 

p2++; 

if (pO > 11) 
pO = 0; 
if (pi > 11) 
pi = 0; 
if (p2 > 11) 

p2 = 0; 

for (scale=0.1; scale<1.0; scale += 0.2) 

set_segment_image_transformation_2 (CLOUD, 
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0.5 * scale, scale, 0.0, 
clx, cly + scale * 0.2); 

} 

deselect_view_surf ace (Svsurf ) ; 
terminate_core () ; 

} 



1.2. The Factory Drawing First, here are die coordinates for the outline of the factory itself: The next set of 
Function declarations describe the outline of the windows in the factory: Now we have the 

actual code of the factory drawing function itself: The xO and yO arguments to 
the factory function describe the absolute position in world coordinates at which 
the factory should appear. The actual outline of the factory is described by the 
array of coordinates declared above. Now we draw the windows within the fac- 
tory: The next function is the one which draws the Sun Workstations within the 
workstation segment. 

Figure 1-3 factory . c Function 

■> 

#include <usercore.h> 
tinclude "factory. h” 

static float factdx[] = {0.0, 0.0, 8.0, 2.0, 3.0, 2.0, 3.0, 

1.0, 3.0, 1.0, 17.0, 0.0, -40.0}; 
static float factdy[] = {0.0, 20.0, 0.0, 20.0, 0.0, -20.0, 

0.0, 15.0, 0.0, -15.0, 0.0, -20.0, 0.0}; 
static float winddx[] = {0.0, 0.0, 10.0, 0.0, -10.0}; 
static float winddy[] = {0.0, 5.0, 0.0, -5.0, 0.0}; 
static int black = 3; 
static int brick = 1; 

factory(x0, yO) 
float xO, yO; 

{ 

set_fill_index (brick) ; 

move_abs_2 (xO, yO) ; /* Move to appropriate position */ 
polygon_rel_2 (factdx, factdy, 12); /* Draw the factory outline */ 

set_fill_index (black) ; 

move_rel_2 (5 . 0 , 10.0); /* Move to position of first window */ 

polygon_rel_2 (winddx, winddy, 4); /* and draw the window */ 

move_rel_2 (15 . 0, 0.0); /* Move to position of second window */ 

polygon_rel_2 (winddx, winddy, 4); /* and draw the window */ 

set_f ill_index (1) ; /* reset fill index */ 

} 
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1.3. The Workstation The declarations below describe the outline of the Sun Workstation. Tube 

Drawing Function describes the screen, Case describes the outer outline of the case, base describes 

the base of the Workstation, and keybd describes the appearance of the keyboard: 
Then all we have to do is move to the coordinates that were supplied as function 
arguments, and draw the lines: 



Figure 1-4 sunws . c Function 



#include <usercore.h> 
tinclude "factory. h" 



static 


float 


tubex [ ] = 


O 

o 


5 


.0, 


0 

Lf> 

1 

o 

o 




static 


float 


tubey [ ] = 


{5.0, 


0 


.0, 


-5.0, 0.0); 




static 


float 


casex[] = 


(1.0, 


7 


.0, 


1.0, 1.0, - 


1.0, -7.0, -1.0}; 


static 


float 


casey[] = 


{7.0, 


0 


.0, 


-7.0, 1.0, 


o 

I— 1 
1 

o 

o 

o 


static 


float 


basex[] = 


{9.0, 


- 


1.0 


, -1.0, -5.0 


, -1.0}; 


static 


float 


basey [] = 


{0.0, 


0 


.0, 


-2.0, 0.0, 


2.0}; 


static 


float 


keybdx [ ] = 


{0.0 


r 


10. 


0, 3.0, 0.0, 


-10.0, -3.0, 10. 


static 


float 


keybdy [ ] = 


{-1. 


0, 


0. 


0, 2.0, 2.0, 


o 

o 

0 

00 

1 

o 

o 



3.0}; 



sunws (xO, yO) 
float xO, yO; 

{ 

move_abs_2 (xO+5 . 0, yO+8.0); /* Move to the position given */ 
polyline_rel_2 (tubex, tubey, 4); /* Draw the tube */ 

move_rel_2 (-2 . 0, -1.0); 

polyline_rel_2 (casex, casey, 7); /* Draw the case */ 



move_rel_2 (-1 . 0, -7.0); 

polyline_rel_2 (basex, basey, 5); /* Draw the base */ 

move_abs_2 (xO, yO+1.0); 

polyline_rel_2 (keybdx, keybdy, 8); /* Draw the keyboard */ 



1.4. The Chip Drawing 
Function 



The declarations below describe the outline of the chips. Plasti describes the out- 
line of the chip itself, while lead describes the outline of the leads on the chip: 
Then all we have to do is move to the coordinates that were supplied as function 
arguments, and draw the lines: 
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Figure 1-5 chip . c Function 



tinclude <usercore.h> 

# include "factory.h" 

static float plastix[] = {0.0, 16.0, 0.0, -16.0}; 
static float plastiy[] = {4.0, 0.0, -4.0, 0.0}; 



static float leadx[] = {-1.0, 2.0, -1.0, 0.0}; 
static float leady[] = {2.0, 0.0, -2.0, -4.0}; 



chip(x0, yO) 
float xO, yO; 
{ 

short i; 



set_rasterop (XORROP) ; 

move_abs_2 (xO, yO) ; /* Move to appropriate position */ 
polyline_rel_2 (plastix, plastiy, 4) ; /* Draw the chip */ 

move_rel_2 (2.0, 1.0); 

for (i=0; i<5; i++) { /* Draw the leads on the chip */ 

polyline_rel_2 (leadx, leady, 4) ; 
move_rel_2 (3.0, 4.0); 

} 

set_rasterop (NORMAL) ; /* Reset rasterop */ 



1.5. The Cloud Drawing The last function is the one that draws the cloud. The cloud function is easy: all 

Function we have to do is draw its outline. The actual scaling of the cloud is done in the 

main program. 

The declarations below describe the outline of the cloud: Then all we have to do 
is move to the coordinates that were supplied as function arguments, and draw 
the lines: 
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Figure 1-6 cloud . c Function 

#include <usercore.h> | 

finclude "factory. h" 

static float cloudx[] 



static float cloudy [] 



cloud(xO, yO) 
float xO, yO; 

{ 

move_abs_2 (xO, yO) ; 

polyline_rel_2 (cloudx, cloudy, 21); 

} 

. ) 



{0. 


0, 


CO 

o 


-8. 


0, 


-4.0, 


2. 


0, 


14 


.0, 


8 . 


.0, 


0.0, 


12. 


0, 


CO 

o 


4.0 


9 


o 

0 

1 


10. 


0, 


10 


.0, 


4. 


.0, 


1 

o 


-6. 


0, 


-12.0 


/ " 


6. 


0, -12 


.0, 


- 


10. 


0}; 








{12 


.0, 


00 

o 


2. 


0, 


6.0, 


6.0 


f 


10 . 


0, ■ 


-4, 


.0, 


-6.0 


10. 


0, 


o 

o 
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0, 


1 

o 

o 


r “ 


10 


.0, 
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0. 
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0}; 
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terminology, 3 thru 6 
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control, 17 
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